【布道 API】API 端点 / 资源命名最佳实践

有很多理由来驱动深思熟虑地命名 API 端点，为 API 端点选择合理的名称可以极大地平滑新开发人员的学习曲线，帮助他们直观地知道要寻找什么以及在哪里找到它，也能极大的降低开发人员之间的沟通成本。本文将介绍 API 端点命名的实用规范，关于 REST 的设计准则，可以参阅《9个REST API设计的基本准则》，在开始讨论 API 命名实践之前，先聊下 REST 的资源命名准则。

RESTful 资源命名准则

先来看看特定于 REST 的命名准则，其中一些命名实践同样适合其他风格的 API，但常见于 RESTful API “端点”的命名中。

根据 Roy T. Fielding 本人的说法，没有“REST 端点”这样的东西。有资源，一组仅受 URL 长度限制限制的资源，通常资源被当做端点的子集来用。

名词 URI 作为资源

REST 易懂的特征之一是在 URI 中主要使用名词。RESTful URI 不应该使用任何类型的 CRUD（创建、读取、更新、删除）功能，URI 应该用于唯一标识资源，而不是对它们进行任何操作。因此，REST API 应该允许通过一个 HTTP 方法操作资源，资源应该采用名词的形式。

示例： /users/{id} 代替 /getUser

“RESTful URI 应该引用一个事物（名词）的资源，而不是引用一个动作（动词），因为名词具有动词没有的属性——就像资源具有属性一样。” —— RESTfulAPI.net

多元化的资源

接下来是资源名称是否应该是复数的问题，显然，这是一个偏好问题，但是，经验丰富的 API 设计者会建议将所有资源多元化，除非它们是单一资源。

例如：/users （典型资源） 或 /users/{id}/address （单例资源）

使用斜杠 / 表示层次关系

如上面的例子所示，斜杠/ 通常用于显示单个资源和集合之间的层次结构。

例如:：/users/{id}/address 显然属于 /users/{id} 的资源，该资源属于 /users 集合。

“层次结构：没有任何强制规定，只需确保强加的结构对开发有意义。与软件开发工艺中的所有事情一样，命名是成功的关键。” ——RESTAPITutorial.com

标点符号的列表

当没有层次关系时（如在列表中），应该使用分号之类的标点符号或者常见的逗号。

例如：/users/{id1},{id2} 访问多个用户资源。

必要时查询参数

为了对集合进行排序或过滤，REST API 允许在 URI 中传递查询参数。 例如：/users?location=shenzhen 查找位于 shenzhen 的所有用户

使用连字符 - 提高可读性

为了使 URI 容易被开发人员理解，建议使用连字符-字符来提高长较长名称的可读性。

例如：/users/{id}/pending-orders 替代 /users/{id}/pendingorders

不要使用下划线_

虽然可以用下划线 _ 代替连字符 - 作为分隔符，但有些应用程序的字体，下划线 _ 字符可能会在某些浏览器或屏幕中部分被遮住或完全遮住。

为避免这种混淆，建议使用连字符 - 而不是下划线 _ 。

例如：/users/{id}/pending-orders 替代 /users/{id}/pending_orders

使用小写字母

RFC 3986 将 URI 定义为区分大小写，对于不同环境，大小写 URI 代表不同的路径，为了避免混淆，建议在 URI 中应始终使用小写字母。

端点/资源命名

上面介绍了常见的 REST API 资源命名规范，然而，无论 API 是否是 RESTful 风格，都应该坚持一些通用的命名规范。

直观的名称（不用术语）

让端点名字更直观！在可能的情况下，选择最简单和最常用的词来代替给定的概念。如果操作正确，大多数端点/资源名应该是可以猜到其用途的，这样开发人员就不必去查看 API 文档了。

作为这一点的延伸，避免使用术语。知识渊博的开发人员对术语可能没有什么障碍，但大多数开发人员对于行业术语不一定都听过。

不省略（不用缩写）

避免省略端点/资源名，现代 WEB 技术、网络环境和设备，没这个必要节省了。事实上，缩写的名称实际上会在 API 中造成混淆，开发人员很难猜测（有时甚至理解）所选择的名称。

例如： /users/{id}/phone-number 代替 /users/{id}/tel-no

不用扩展名

不要在 URI 中使用文件扩展名（例如.xlsx），相对来说很难看，而且给增加了 URI 长度。如果需要指定内容的格式，建议使用Content-Type。

例如： /users/{id}/pending-orders 代替 /users/{id}/pending-orders.xlsx，Content-Type:application/vnd.ms-excel;charset=utf-8;

不用斜杆 / 结尾

同样，为了保持 URI 的整洁，不要在 URI 的末尾添加一个斜杠 / ，会增加语义值并可能导致混淆，最好完全放弃。

例如： /users/{id}/pending-orders 代替 /users/{id}/pending-orders/

末尾的斜杠必须没有特定的语义，资源路径必须提供相同的结果，不管它们是否有末尾的斜杠。 —— Zalando RESTful API and Event Guidelines

一致性是关键

端点命名的一致性原则是必须要遵守的，就算严格遵照上述约定，如果名称不一致，API 总是会感到特别别扭。在 API 中总是使用相同的名称来引用给定的资源。

本文所述的端点命名规范，有其片面性，实际开发中会有更加友好的规范，但不管何种规范何种风格，都需要确保端点名称与文档中使用的名称以及应用程序本身（如果适用）使用的名称保持一致。

例如： /users 应该记录在 users 资源下，而不是 getUser 方法下。

总结

以上总结了一些项目用得上的 API 端点/资源的命名规范，像简洁直观的命名规范肯定对开发人员很友好！对于更细粒度的 API 设计规范，推荐阅读Zalando RESTful API and Event Guidelines。