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- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
使用 JSON 来定义 body 信息
比如在增加学生时把学生定义为
{ "name": "Tom", "gender": "male". "age": 15}- 1
- 2
- 3
- 4
- 5
然后使用 POST 命令来增加资源
POST /students/- 1
使用 POST 来执行控制命令
POST 除了可以用来增加资源，还被用来针对资源执行命令，比如：
# 激活ID=996的名声账号POST /student/activate/996- 1
- 2
上例中 activate 就是控制命令
使用 2xx 表示操作执行成功
这是 W3C 的国际标准：
比如 200 表示成功，201 表示创建成功等。
使用 4xx 表示操作出现错误
按照 W3C 国际标准应该使用 4xx 返回码表示各种错误，而不应该所有的返回都用 200，然后通过返回消息来找到错误。4xx 码都有特定的含义，比如注明的 404 就表示找不到某个资源。更多的错误码描述可以查看：
使用 ProblemDetail 来定义返回错误信息
我们看到很多 API 都是自己定义错误信息的返回格式，其实早有错误格式的工业标准，这就是 使用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"]}- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
上面的示例中 type, title, detail, instance 是标准选项，balance下面的信息是自定义选项。几乎每种主流编程语言都有支持这个标准的解决方案。