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=15
# 查询学生的学校
GET /student-schools# 增加学生
POST /students
# 修改id=996的学生的信息
PUT /student/996

使用 JSON 来定义 body 信息

比如在增加学生时把学生定义为

{"name": "Tom","gender": "male"."age": 15
}

然后使用 POST 命令来增加资源

POST /students/

使用 POST 来执行控制命令

POST 除了可以用来增加资源，还被用来针对资源执行命令，比如：

# 激活ID=996的名声账号
POST /student/activate/996

上例中 activate 就是控制命令

使用 2xx 表示操作执行成功

这是 W3C 的国际标准： https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

比如 200 表示成功，201 表示创建成功等。

使用 4xx 表示操作出现错误

按照 W3C 国际标准应该使用 4xx 返回码表示各种错误，而不应该所有的返回都用 200，然后通过返回消息来找到错误。4xx 码都有特定的含义，比如注明的 404 就表示找不到某个资源。更多的错误码描述可以查看：

https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html

使用 ProblemDetail 来定义返回错误信息

我们看到很多 API 都是自己定义错误信息的返回格式，其实早有错误格式的工业标准，这就是 RFC 7807 使用Problem Detail 来返回错误信息。

这是它的样子：

// For example, an HTTP response carrying JSON problem details://  HTTP/1.1 403 Forbidden
//  Content-Type: application/problem+json
//  Content-Language: en
{"type": "https://example.com/probs/out-of-credit","title": "You do not have enough credit.","detail": "Your current balance is 30, but that costs 50.","instance": "/account/12345/msgs/abc","balance": 30,"accounts": ["/account/12345","/account/67890"]
}

上面的示例中 type, title, detail, instance 是标准选项，balance下面的信息是自定义选项。几乎每种主流编程语言都有支持这个标准的解决方案。