RESTful规范

协议

• API与用户通信协议使用HTTPS

域名

• 尽量将API放入专有域名下

版本号

• 将版本号放入URL中

路径

• 在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。

• 举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees

HTTP动词

• GET（SELECT）：从服务器取出资源（一项或多项）。
• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
• DELETE（DELETE）：从服务器删除资源。
• HEAD：获取资源的元数据。
• OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。

过滤信息

• 如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。
  下面是一些常见的参数。

?limit=10：指定返回记录的数量
?offset=10：指定返回记录的开始位置。
?page=2&per_page=100：指定第几页，以及每页的记录数。
?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
?animal_type_id=1：指定筛选条件

状态码

200系列

• 200 OK 请求成功（其后是对GET和POST请求的应答文档。）
• 201 Created 请求被创建完成，同时新的资源被创建。
• 202 Accepted 供处理的请求已被接受，但是处理未完成。

300系列

• 300 Multiple Choices 多重选择。链接列表。用户可以选择某链接到达目的地。最多允许五个地址。
• 301 Moved Permanently 所请求的页面已经转移至新的url。
• 302 Found 所请求的页面已经临时转移至新的url。

400系列

• 400 Bad Request 服务器未能理解请求。
• 401 Unauthorized 被请求的页面需要用户名和密码。
• 402 Payment Required 此代码尚无法使用。
• 403 Forbidden 对被请求页面的访问被禁止。
• 404 Not Found 服务器无法找到被请求的页面。

500系列

• 500 Internal Server Error 请求未完成。服务器遇到不可预知的情况。
• 501 Not Implemented 请求未完成。服务器不支持所请求的功能。
• 502 Bad Gateway 请求未完成。服务器从上游服务器收到一个无效的响应。
• 503 Service Unavailable 请求未完成。服务器临时过载或当机。
• 504 Gateway Timeout 网关超时。

返回错误

• 如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{
error: "Invalid API key"
}

返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

• GET /collection：返回资源对象的列表（数组）
• GET /collection/resource：返回单个资源对象
• POST /collection：返回新生成的资源对象
• PUT /collection/resource：返回完整的资源对象
• PATCH /collection/resource：返回完整的资源对象
• DELETE /collection/resource：返回一个空文档