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下面的信息是自定义选项。几乎每种主流编程语言都有支持这个标准的解决方案。