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
