RESTful API 设计规范

路径

路径又称为端点，表示API的具体地址。在路径的设计中，需遵守下列约定：

• 命名必须全部小写
• 资源（resource）的命名必须是名词，并且必须是复数形式
• 如果要使用连字符，建议使用‘-’而不是‘_’，‘_’字符可能会在某些浏览器或屏幕中被部分遮挡或完全隐藏
• 易读

命名必须全部小写和易读都无需解释，可以理解为规定，那么为什么命名必须是名词且需要复数形式呢？这是因为在RESTful中，主语是资源，资源肯定是名词，不能是动词。其次，一个资源往往对应数据库中一张表，表就是实体的集合，因此需要是复数形式。

下面是一些反例：

• api.example.com/getUser
• api.example.com/addUser

下面是一些正例：

• api.example.com/zoos
• api.example.com/zoos/animal…

HTTP动词

对于如何操作资源，有相应的HTTP动词对应，常见的动词有如下五个（括号里表示SQL对应的命令）：

• GET（SELECT）：从服务器取出资源（一项或多项）
• POST（CREATE）：在服务器新建一个资源
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）
• DELETE（DELETE）：从服务器删除资源

示例：

HTTP动词	路径	表述
GET	/zoos	获取所有动物园信息
POST	/zoos	新建一个动物园
GET	/zoos/ID	获取指定动物园的信息
PUT	/zoos/ID	更新指定动物园的信息（前端提供该动物园的全部信息）
PATCH	/zoos/ID	更新某个指定动物园的信息（提供该动物园改动部分的信息）
DELETE	/zoos/ID	删除某个动物园
GET	/zoos/ID/animals	获取某个动物园里面的所有动物信息

参考文献：

RESTful API 设计规范 - 掘金 (juejin.cn)