RESTful API的设计策略
RESTful API是目前较成熟的一套互联网应用程序API设计理论；这里主要介绍下如何通过RESTful API设计出一套合理好用的API接口。
协议
API与用户的通信协议，总是要使用HTTPs协议。
注：如果想要了解HTTPs协议的设计思想和运行过程，可访问SSL/TLS协议运行机制
域名
应该尽量将API部署在专用域名之下：1
https://api.example.com/
如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下：1
https://exampl.org/api/
版本
应该将API的版本号放入URL:1
https://api.example.com/v1/
另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。
路径
路径又称”终点(endpoint)”，表示API的具体网址。
在RESTful架构中，每一个网址代表一种资源，而资源的名称往往与数据库的表明对应。一般来说，数据库中的表都是同种记录的”集合”，所以API中的资源名称也该使用复数。
如下面这个API提供动物园的信息，包括各种动物和雇员。路径设计如下：1
2
3https://api.example.com/v1/zoos
https://api.example.com/v1/animals
https://api.example.com/v1/employees
HTTP动词
HTTP动词是指对资源的集体操作方式的类型。
常用的HTTP动词有以下五个：
| 动词名称 | SQL命令 | 含义 |
|---|---|---|
| GET | SELECT | 从服务其取出资源(一项或多项) |
| POST | CREATE | 在服务器新建一个资源 |
| PUT | UPDATE | 在服务器更新资源(客户端提供改变后的完整资源) |
| PATCH | UPDATE | 在服务器更新资源(客户端提供改变的属性) |
| DELETE | DELETE | 从服务器删除资源 |
还有两个不常用的HTTP动词：
| 动词名称 | 含义 |
|---|---|
| HEAD | 获取资源的元数据 |
| OPTIONS | 获取信息，关于资源的哪些属性是客户端可以更改的 |
例如：
- GET /zoos：列出所有动物园
- POST /zoos：新建一个动物园
- GET /zoos/ID：获取某个指定动物园的信息
- PUT /zoos/ID：更新某个指定动物园的信息(提供次动物园全部信息)
- PATCH /zoos/ID：更新某个指定动物园的信息(提供次动物园的部分信息)
- DELETE /zoos/ID：删除某个动物园
- GET /zoos/ID/animals：列出某个指定动物园的所有动物
- DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物
过滤信息
如果记录数量很多，服务器不可能都将他们返回给客户端。API应该提供参数，过滤返回结果。
下面是一下常见的参数：
- ?limit=10：指定返回记录的数量
- ?offset=10：指定返回记录的开始位置
- ?page=2&per_page=100：指定第几页，以及每页的记录数
- ?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序
- ?animal_type_id=1：指定筛选条件
参数的设计允许存在冗余，即允许API路径和URL参数偶尔有重复指向同一资源。比如：GET /zoos/ID/animals与GET /animals?zoos_id=ID的含义相同。
状态码
服务器向用户返回的状态码和提示信息，常见的如下面所示：
| 状态码 | HTTP动词 | 含义 |
|---|---|---|
| 200 OK | GET | 服务器成功返回用户请求的数据，该操作是幂等的。 |
| 201 CREATED | POST/PUT/PATCH | 用户新建或修改数据成功 |
| 202 Accepted | * | 表示一个请求已经进入后台排队(异步任务) |
| 204 NO CONTENT | DELETE | 用户删除数据成功 |
| 400 INVA:ID REQUEST | POST/PUT/PATCH | 用户发出的请求有错误，服务器没有进行新建或者修改数据的操作，该操作是幂等的 |
| 401 Unauthorized | * | 表示用户没有权限(令牌、用户名、密码错误) |
| 403 Forbidden | * | 表示用户得到授权，但访问是被禁止的 |
| 404 NOT FOUND | * | 用户发出的请求对应是不存在的记录，服务器没有进行操作，该操作是幂等的 |
| 406 Not Acceptable | GET | 用户请求的格式不可得 |
| 410 Gone | GET | 用户请求的资源被永久删除，且不会在得到 |
| 422 Unprocesable entity | POST/PUT/PATCH | 当创建一个对象时，发生一个验证错误 |
| 500 INTERNAL SERVER ERROR | * | 服务器发生错误，用户将无法判断发出的请求是否成功 |
状态码完整列表在这里
错误处理
如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可:1
2
3{
error: "Invalid API key"
}
返回结果
针对不同操作，服务器向用户反蝴蝶结果应该符合一下规范：
- GET /collection：返回资源对象列表(数组)
- GET /collection/resource：返回单个资源对象
- POST /collection：返回新生成的资源对象
- PUT /collection/resource：返回完整的资源对象
- PATCH /collection/resource：返回完整的资源对象
- DELETE /collection/resource：返回一个空文档
Hypermedia API
RESTful API最好做到Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档也知道下一步应该做什么。
比如，当用户像api.example.com的根目录发出请求，会得到这样一个文档：1
2
3
4
5
6
7
8{
“link”: {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}
}
上面代码表示，文档有一个link属性，用户读这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系，href表示API的路径，title表示API的标题，type表示返回类型。
Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表：1
2
3
4
5{
“current_user_url”： "https://api.github.com/user"，
“current_user_authorizations_html_url”： "https://github.com/setti…applications{/client_id}"
// ...
}
从上面可以看到，如果想获取当前用户的信息，应该去访问api.github.com/user，然后就得到下面结果：1
2
3
4{
"message": "Requires authentication",
"documentation_url": "https://developer.github.com/v3/users/#get-the-authenticated-user",
}
上面代码表示，服务器给出了提示信息，以及文档的网址。
其他
- API的身份认证应该使用OAuth 2.0框架.
- 服务器返回的数据格式，应该尽量使用JSON，避免使用XML.
参考资料：restful api设计