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：删除某个指定动物园的指定动物

1|0API 设计黄金法则

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

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

2|0最佳实践

2|1URL命名规则

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

2|2根据返回资源定义URL

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

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

URL标识一种资源，所以规范的URL是以集合开始以ID结束
不推荐：GET /category/:categoryId/price 推荐：GET /category/:categoryId

2|4URL中不添加动作

不要在URL中使用动词来表达你的意图。相反，使用适当的HTTP方法来描述操作。
不推荐：POST /updateuser/{userId} GET /getusers
推荐：PUT /user/{userId}

2|5不使用表名做URL

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

2|6使用版本号

建议在 URL 中包含 API 的版本号。
https://example.com/api/v1/... <-- 第一版 API
https://example.com/api/v2/... <-- 第二版 API
好处是：1. API 升级不影响调用方的代码，2. 升级后的 API 可以不向前兼容。

2|7对非资源URL使用动词

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

__EOF__

本文作者：goldsunshine
本文链接：https://www.cnblogs.com/goldsunshine/p/16407144.html
关于博主：评论和私信会在第一时间回复。或者直接私信我。
版权声明：本博客所有文章除特别声明外，均采用 BY-NC-SA 许可协议。转载请注明出处！
声援博主：如果您觉得文章对您有帮助，可以点击文章右下角【推荐】一下。您的鼓励是博主的最大动力！