API 设计最佳实践（简版）

Restful API 本文简称API，是一个种面向资源的架构。在Restful中一个API对应一个资源，资源可以是文本，图片，视频等。API特征有如下：

• 每一个URI代表一种资源
• 客户端和服务器之间，传递这种资源的某种表现层
• 客户端通过HTTP动词，对服务器端资源进行操作，实现表现层状态转化

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面五个（括号里是对应的SQL命令）另外有两个不常用。

GET（SELECT）：从服务器取出资源（一项或多项）。
POST（CREATE）：在服务器新建一个资源。
PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
DELETE（DELETE）：从服务器删除资源。
HEAD：获取资源的元数据。
OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

下面是一些例子。

GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物

API 设计黄金法则

对API格式的决定有疑问，黄金规则可以帮助我们做出正确的决定：

• 扁平比嵌套好
• 简单胜于复杂
• 字符串比数字好
• 一致性比定制更好

最佳实践

URL命名规则

• URL请求采用小写字母，数字，部分特殊符号组成
• URL请求中不采用大小写混合的驼峰命名方式，尽量采用全小写单词
• 如果需要连接多个单词，则采用连接符短横"-"或下划线"_"连接单词，且保持风格统一

根据返回资源定义URL

• 获取单数的集合使用单数名词
• 获取复数的集合使用复数的名词 不推荐：GET /user 推荐：GET /users

URL以集合开始，以标识符结束

URL标识一种资源，所以规范的URL是以集合开始以ID结束

不推荐：GET /category/:categoryId/price 推荐：GET /category/:categoryId

URL中不添加动作

不要在URL中使用动词来表达你的意图。相反，使用适当的HTTP方法来描述操作。

不推荐：POST /updateuser/{userId} GET /getusers

推荐：PUT /user/{userId}

不使用表名做URL

不要只使用表名作为资源名。从长远来看，这种懒惰是有害的，这是因为表名会公开底层体系结构。

不推荐：product_order 推荐：product-orders

使用版本号

建议在 URL 中包含 API 的版本号。

https://example.com/api/v1/... <-- 第一版 API

https://example.com/api/v2/... <-- 第二版 API

好处是：1. API 升级不影响调用方的代码，2. 升级后的 API 可以不向前兼容。

对非资源URL使用动词

如果你有一个端点，它只返回一个操作。在这种情况下，你可以使用动词。例如，如果你想要向用户重新发送警报。推荐：POST /alarm/245743/resend