REST API 设计最佳实践
Best practices for REST API design - Stack Overflow
REST API 是最常见的 Web 服务类型之一。浏览器、应用程序等各种客户端 都可以通过 REST API与服务器通信。
正确设计 REST API 非常重要， 我们要考虑 REST API 的安全性、性能和易用性。
什么是 REST API
REST API 是一种应用程序编程接口, 它符合特定的体系结构约束，如无状态通信和可缓存数据。它不是协议或标准。
虽然 REST API 可以通过多种通信协议进行访问，但最常见的是通过 HTTPS 。
以下准则适用于将通过 Internet 调用的 REST API 端点。
注意：对于通过互联网调用的 REST API，您需要遵循 REST API 身份验证的最佳实践。
使用 JSON 作为输入和响应
REST API 应以 JSON 作为数据传输标准：
- 接受 JSON 作为请求负载
- 通过 JSON 发送响应。
JSON 是传输数据的标准，无论是客户端还是服务器端，使用JSON都很方便。
表单比较适合发送文件。但对于文本和数字，我们可以直接在客户端从中获取JSON传输。这样最直接。
在返回JSON时，应该设置响应标头，`Content-Type: application/json`。不过很多库会自动替我们设置这个标头。
在路径中使用名词而不是动词
我们不应该在端点路径中使用动词。相反，应该使用相关实体的名词，作为路径名。
这是因为我们的 HTTP 请求方法已经具有动词。在我们的 API 终结点路径中使用动词是没有用的。它不传达任何新信息，只是显得冗长，而且，所选动词可能因开发人员的心血来潮而异。例如，有人用“get”，有人用“retrieve”。
所以最好让HTTP GET动词告诉我们和端点的作用。
最常用的方法包括 GET、POST、PUT 和 DELETE。
- GET 检索资源。
- POST 将新数据提交到服务器。
- PUT 会更新现有数据。
- DELETE 删除数据。
动词映射到 CRUD 操作。比如：
- GET /articles 获得取文章列表
- GET /articles/:id 获得某篇文章
- POST /articles 创建新文章
- PUT /articles/:id 修改某篇文章
- DELETE /articles/:id 删除某篇文章
在路径中使用资源嵌套
在实际中，一个资源可能包含其它资源，比如一篇文章可能包含多个评论。我们要设计合理的路径来表示这种嵌套。
注意：REST API 路径中的资源嵌套最好不要照搬数据库的表结构，以免后台数据结构的泄露。
比如，GET /articles/:articleId/comments 得到某篇文章的所有评论。
然而，这种嵌套可能有很多层，尤其在二三层之后，这种结构就会变得很笨拙。这时候，就可以通过返回对象的URL 来终止这种嵌套。
比如：你想得到某篇文章的某个评论的作者，与其返回某个 articleId 中大而全的结构，不如在 /articles/:articleId/comments/:commentId/author 中直接返回 URI "author": "/users/:userId"
这个，客户端在拿到地址之后，可以再根据接口，拉取更详细的信息。避免一次查询过于臃肿。
优雅地处理错误 - 返回有效的信息
API 出错可能有多种情况，但我们可以把出错分为两大类：
- HTTP 协议级出错
- 上层应用逻辑出错
周全考虑，我们应该返回 HTTP 返回码和应用逻辑状态码。HTTP 返回码通常是标准的，而应用逻辑状态码需要我们自己约定。
使用 HTTP 标准返回码
常见的 HTTP 状态码包括：
- 200 OK - HTTP 请求正常
- 400 BAD REQUEST - 请求的参数格式错误
- 401 UNAUTHORIZE - 认证未通过（比如用户名密码错，导致不能通过认证)
- 403 FORBBIDEN - 没有授权
- 404 NOT FOUND - 找不到资源，这个有时候会被电信运营商劫持
- 500 INTERNAL SERVER ERROR - 通用的服务器内部错误
- 502 BAD GATEWAY - 上游服务出错
- 503 SERVICE UNAVAILABLE - 服务不可用
还应加上应用状态信息
除了认真返回 HTTP 状态码之外，我们还应该在返回内容中增加 err 部分，添加更细致的返回/出错状态信息。
比如，数据库连接失败：
{
"status": 502,
"err": {
"code": 502001,
"msg": "后台数据库连接失败"
},
"data": {
}
} |
如果正常：
{
"status": 200,
"err": {
"code": 0,
"msg": "",
},
"data": {
正常的返回数据
} |
支持分页、筛选、排序
REST API 背后的数据可能非常大，我们需要提效分页和筛选功能，以提高效率。
比如：/employees?lastName=Smith&age=30&page=2
或者：/aritcles?sort=+author, -datepublished 加号、减号代表排序顺序
加强安全
- 使用 TLS/SSL
- 贯彻最小特权原则 - 普通用户应该无法访问其他用户的信息，不能访问管理员的数据。不同角色的权限要有明确的控制。
使用缓存提高性能
使用缓存有助于提高性能，因为不用每次都查询数据库了。当然，缓存有可能过时，导致调试了生产时的一些问题。使用时要特别小心。
缓存的解决方案有 Redis, Memcache 等。
注意应在标头中使用 Cache-Control 来为使用者提供更详细的指引。
API 版本控制
API 接口改动可能会引起客户端的更改，为了提供更好的兼容性，我们应该提供版本控制。
常见的做法是在 API 路径开头提供 /v1 /v2 这样的前缀来表示API的版本。 /employees?lastName=Smith&age/employees?lastName=Smith&age=30