14.Restful API接口设计规范
前言
RESTful API 设计规范是确保接口一致性、可维护性和易用性的关键。以下是一份全面且结构化的指南
一、什么是 RESTful 架构
REST是Representational State Transfer的缩写，如果一个架构符合REST原则，就称它为RESTfuI架构RESTfuI架构可以充分的利用HTTP协议的各种功能，是HTTP协议的最佳实践RESTfuIAPI是一种软件架构风格、设计风格，可以让软件更加清晰，更简洁，更有层次，可维护性更好
二、API请求设计（请求=动词+宾语）
HTTP动词
动词 使用五种 HTTP 方法，对应 CRUD 操作。
GET： 读取（Read）POST： 新建（Create）PUT： 更新（Update）PATCH： 更新（Update），通常是部分更新DELETE：删除（Delete）
URL（宾语）必须是名词
宾语就是 API 的 URL，是 HTTP 动词作用的对象。它应该是名词，不能是动词。并且为了统一起见，建议都使用复数。比如，/articles这个 URL 就是正确的，而下面的 URL 不是名词，所以都是错误的。
/getAllCars>/createNewCar>/deleteAllRedCars
- 过滤信息（Filtering）
过滤信息（Filtering）如果记录数量很多，API应该提供参数，过滤返回结果。?limit=10指定返回记录的数量？offset=10指定返回记录的开始位置。下面是一些常见的参数。
?limit=10：指定返回记录的数量?offset=10：指定返回记录的开始位置。?page=2&per_page=100：指定第几页，以及每页的记录数。?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。?animal_type_id=1：指定筛选条件
参数的设计允许存在冗余，即允许 API 路径和 URL 参数偶尔有重复。比如，GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
API请求设计
| HTTP 动词 | URL（宾语) | API 请求 |
|---|---|---|
| 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响应设计
- 使用
HTTP的状态码
- 客户端的每一次请求，服务器都必须给出回应。回应包括
HTTP状态码和数据两部分。 - 五大类状态码，总共 100 多种，覆盖了绝大部分可能遇到的情况。每一种状态码都有约定的解释，客户端只需查看状态码，就可以判断出发生了什么情况。
HTTP状态码就是一个三位数，分成五个类别。
1xx：相关信息：表示请求已接收，继续处理。 2xx：操作成功：表示请求已成功被接收、理解、并被接受。 3xx：重定向：表示需要进一步操作以完成请求。 4xx：客户端错误：表示请求包含语法错误或无法完成。 5xx：服务器错误：表示服务器在处理请求时发生了错误。
API不需要1xx状态码。
- 状态码
| 状态码 | 含义 |
|---|---|
| 1xx | API 不需要1xx状态码 |
| 2xx | 成功状态码 |
| 200 | OK：请求成功，服务器已成功处理请求。 |
| 201 | Created：请求成功，服务器已创建资源。 |
| 204 | No Content：请求成功，但没有返回任何内容。 |
| 3xx | 重定向状态码 |
| 301 | Moved Permanently：资源已永久移动到新位置。 |
| 302 | Found：资源临时移动到新位置。 |
| 304 | Not Modified：资源未修改，客户端可以使用缓存的版本。 |
| 4xx | 客户端错误状态码 |
| 400 | Bad Request：请求语法错误，服务器无法理解请求。 |
| 401 | Unauthorized：请求需要用户认证。 |
| 403 | Forbidden：服务器拒绝请求，即使已经认证成功。 |
| 404 | Not Found：请求的资源不存在。 |
| 405 | Method Not Allowed：用户已经通过身份验证，但是所用的 HTTP 方法不在他的权限之内。 |
| 5xx | 服务器错误状态码 |
| 500 | Internal Server Error：服务器在处理请求时发生了内部错误。 |
| 502 | Bad Gateway：网关或代理服务器从上游服务器收到无效响应。 |
| 503 | Service Unavailable：服务器当前无法处理请求，可能是由于过载或维护。 |
四、服务器回应数据
- 不要返回纯本文
API 返回的数据格式，不应该是纯文本，而应该是一个 JSON对象，因为这样才能返回标准的结构化数据。所以，服务器回应的HTTP头的Content-Type属性要设为application/json。
客户端请求时，也要明确告诉服务器，可以接受 JSON 格式，即请求的 HTTP 头的ACCEPT属性也要设成application/json。
- 不要包装数据
response 的 body直接就是数据，不要做多余的包装。错误实例：
{ "success": true, "data": { "id": 1, "name": "周伯通" } }
针对不同操作，服务器向用户返回的结果应该符合以下规范。
GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档
- 发生错误时，不要返回 200 状态码
有一种不恰当的做法是，即使发生错误，也返回 200 状态码，把错误信息放在数据体里面，就像下面这样。
{
"status": "failure",
"data": { "error": "Expected at least two items in list." }
}
正确的做法是，状态码反映发生的错误，具体的错误信息放在数据体里面返回。下面是一个例子。
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"error": "Invalid payoad.",
"detail": {
"surname": "This field is required."
}
}
如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将 error 作为键名，出错信息作为键值即可。(error: "Invalid API key"}
- 认证
RESTfuIAPI应该是无状态，每个请求应该带有一些认证凭证。推荐使用JWT认证，并且使用SSL Hypermedia即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么