REST（一）设计风格
rest（一）
常见的rest的实践，主要参考github的api文档，下面总结的只是常用的部分，待补充。
协议
- https方式
版本
- 版本写在URI中，例子：http(s)://api.xxx.com/v1
- 版本也可以写在http的头中
路径
- 网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的”集合”（collection），所以API中的名词也应该使用复数。
HTTP动词
常用的HTTP动词有下面五个（括号里是对应的SQL命令）。
- GET（SELECT）：从服务器取出资源（一项或多项）。
- POST（CREATE）：在服务器新建一个资源。
- PUT（UPDATE）：在服务器更新资源（客户端提供改变后的完整资源）。
- PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
- DELETE（DELETE）：从服务器删除资源。
返回结果
- GET /collection：返回资源对象的列表（数组）
- GET /collection/resource：返回单个资源对象
- POST /collection：返回新生成的资源对象
- PUT /collection/resource：返回完整的资源对象
- PATCH /collection/resource：返回完整的资源对象
- DELETE /collection/resource：返回一个空文档
Schema
- 发送接收都是用JSON格式
- 时间格式可用ISO 8601 format(腾讯与阿里很多api也是此格式):
YYYY-MM-DDTHH:MM:SSZ过滤信息
路径后面的参数，驼峰命名，常用的如下：
- ?limit=10：指定返回记录的数量
- ?offset=10：指定返回记录的开始位置。
- ?page=2&perPage=100：指定第几页，以及每页的记录数。
- ?sortBy=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。
- ?animalTypeId=1：指定筛选条件
返回的码字
- 200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
- 201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
- 202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
- 204 NO CONTENT - [DELETE]：用户删除数据成功。
- 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
- 401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
- 403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
- 404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
- 406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
- 410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
- 422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
- 500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。
认证授权
Basic authentication
curl -u "username" https://api.github.com
OAuth2 token (sent in a header)
curl -H "Authorization: token OAUTH-TOKEN" https://api.github.com
OAuth2 token (sent as a parameter)
curl https://api.github.com/?access_token=OAUTH-TOKEN
分页
默认情况下，如不指定页数，多个条目返回，返回30条。
Hypermedia
这点也是rest的精髓：
All resources may have one or more *_url properties linking to other resources. These are meant to provide explicit URLs so that proper API clients don’t need to construct URLs on their own. It is highly recommended that API clients use these. Doing so will make future upgrades of the API easier for developers. All URLs are expected to be proper RFC 6570 URI templates.