RESTful API

一、有关 RESTful API 的一些术语
资源：一个对象的单独实例。
集合：一群同种对象。
端点：这个 API 在服务器上的 URL 用于表达一个资源或者一个集合。
幂等：无边际效应，多次操作得到相同的结果。
URL 段：在 URL 里面已斜杠分隔的内容。

二、版本化 RESTful API
将 API 部署到二级域名下并带上版本号：
https://api.example.com/v1

三、RESTful API 用到的 HTTP 请求方法
GET (选择)：从服务器上获取一个具体的资源或者一个资源列表。
POST （创建）： 在服务器上创建一个新的资源。
PUT （更新）：以整体的方式更新服务器上的一个资源。
PATCH （更新）：只更新服务器上一个资源的一个属性。
DELETE （删除）：删除服务器上的一个资源。

四、端点
GET /zoos : List all Zoos.
POST /zoos : Create a new Zoo.
GET /zoos/ZID : Retrieve an entire Zoo object.
PUT /zoos/ZID : Update a Zoo (entire object).
PATCH /zoos/ZID : Update a Zoo (partial object).
DELETE /zoos/ZID : Delete a Zoo.

五、滤器、排序、分页
?limit=10 : 分页时限制返回的资源数量。
?offset=10 : 分页时限制资源查找起点。
?topic=soil : 使用条件匹配来过滤记录，条件字段是数据库表的字段。
**?sortby=name&order=asc** : 对结果按特定属性进行排序。

限制 API 返回值的域
GET /ticketsfields=id,subject,customer_name,updated_at&state=open&sort=-updated_at

不符合 CURD 的操作

1. 重构你的行为 action。当你的行为不需要参数的时候，你可以把 active 对应到 activated 这个资源，（更新使用 patch）.
2. 以子资源对待。例如:github 上，对一个 gists 加星操作：PUT /gists/:id/star 并且取消星操作：DELETE /gists/:id/star.
3. 有时候 action 实在难以和某个资源对应上例如 search。那就这么办吧。

六、状态码
200 OK – [GET]：服务器成功找到客户端请求的数据。
201 CREATED – [POST/PUT/PATCH]：服务器创建资源成功。
204 NO CONTENT – [DELETE]：服务器删除资源成功。
400 INVALID REQUEST – [POST/PUT/PATCH]：客户端提供的数据不正确，服务器没有执行操作。
404 NOT FOUND – [GET/POST/PUT/PATCH/DELETE]：客户端引用了一个不存在的资源或集合，服务器没有执行操作。
500 INTERNAL SERVER ERROR – [GET/POST/PUT/PATCH/DELETE]：服务器发生内部错误，客户端无法得知结果，即便请求已经处理成功。

七、返回文档
GET /collection : 返回一系列资源对象。
GET /collection/resource : 返回单独的资源对象。
POST /collection : 返回新创建的资源对象。
PUT /collection/resource : 返回完整的资源对象。
PATCH /collection/resource : 返回完整的资源对象。
DELETE /collection/resource : 返回一个空文档。

八、内容类型
Host: api.example.org
Accept: application/json
Content-Type: application/json
Content-Length: 24

九、HTTP 封包
{
 status ： {
  code : code,
  msg : msg
 }，
 data ：{
  ...
 }
}

文档

命名方式
是蛇形命令（下划线和小写）还是驼峰命名？如果使用 json 那么最好的应该是遵守 JAVASCRIPT 的命名方法-也就是说骆驼命名法。如果你正在使用多种语言写一个库，那么最好按照那些语言所推荐的，java，c#使用骆驼，python，ruby 使用 snake。

参考资料：
https://github.com/aisuhua/restful-api-design-references