RESTful API 命名指南

RESTful API 又叫 Web API, REST 是 representational state transfer 的简写。RESTful API 使用 HTTP 协议的 GET, PUT, POST, PATCH 等操作来定义程序接口。由于这四个操作在 HTTP 协议都有特定的含义，所以我们应该遵循它们的习惯性用法。

• GET 用来查询
• PUT 来修改资源
• POST 用来增加资源或者执行控制命令
• DELETE 用来删除某个资源
• PATCH 用来改变资源的某个属性
  在实际应用中由于只改变资源某个属性的情形较少，所以很多情况下会直接使用 PUT 直接修改资源

这些操作都是针对资源 (resource) 的，为了让用户能够直观准确地理解 API 的使用，我们应该遵循以下约定：

资源名称使用小写

所有 API 都会操作某个资源，资源名称应该是小写的复数形式，比如 students。

• 如果是两个单词组成的资源名称，我们使用减号 “-” 来连接这个两个单词，比如 student schools 写作 student-schools。
• 如果是资源的子集则子集放在斜线后

示例

# 查询所有学生
GET /students
# 查询id=996的学生
GET /students/996
# 查询男生
GET /students/male
# 查询年纪15岁男生
GET /students/male?age=