Restful API 设计指北

友情提示：此篇文章大约需要阅读 11分钟 29秒，不足之处请多指教，感谢你的阅读。 订阅本站
此文章首发于 Debug客栈｜https://www.debuginn.cn

近期学习了Go语言，跟着七米在学习，学习过程中了解到了 API 的一个设计规范，也就是本文要讲的 Restful API 设计模式，现在互联网处在前后端分离的阶段，API 的书写及规范化是非常重要的，针对于 API 中 Restful API 中设计比较规范的是 Github API，可以直接访问他们的 https://api.github.com 直接查看 Github 针对与公共接口的链接及使用方法。

此篇文章也是针对于这几天学习 Restful API 做了一个笔记或小结，若有不足之处还望批评指正，谢谢。

1、使用 HTTPS 协议

这个协议使用本身与这个 API 设计标准没有什么直接联系，使用 HTTPS 协议主要目的是将用户客户端与 API 服务器链接过程中保证其数据的安全性。

注意：由于 API 接口使用 HTTPS 协议，不要让非 SSL 的链接访问重定向到 SSL 的链接。

2、API 地址和版本问题

为 API 使用专门子域名比较友好，例如使用如下链接使用：

https://api.debuginn.cn

也可以将 API 放在主域名下，例如：

https://debuginn.cn/api/

当然，针对于 API 版本问题针对以上两种方法可以分别使用如下例子：

# 针对于 API 子域名方式 api.domain/v1/
https://api.debuginn.cn/v1/
# 针对于 主域名目录方式 domain/api/v1/
https://debuginn.cn/api/v1/

3、Schema 响应数据模式

现在前后端分离项目使用的数据响应模式大部分采用的是 JSON 格式数据，也有一些项目采用 XML 格式的数据。

针对于用户客户端请求，服务器响应尽量有状态码 Status Code 及详细解释。

4、使用正确的 Method

使用正确的 Method 也就是使用正确的 HTTP 请求动词，即 HTTP 协议规定的常常使用的六种请求动词，并针对请求 SQL 语句辅助理解：

GET   请求 => SELECT 从服务端获取数据
POST  请求 => CREATE 从服务端创建数据
PUT   请求 => UPDATE 从服务端更新数据（将所有数据元素全部替换掉）
PATCH 请求 => UPDATE 从服务端更新数据（将部分数据元素替换掉）
DELETE请求 => DELETE 从服务端删除数据

还有两个不常使用的请求：

HEAD    获取资源的元数据。
OPTIONS 获取信息，关于资源的哪些属性是客户端可以改变的。

注意：更新和创建操作应该返回最新的资源，来通知用户资源的情况；删除资源一般不会返回内容。

5、过滤信息

针对用户端查询数据，需要服务端查询对应数据，包括了筛选、分页等操作。

筛选操作

api.domain/user/limit/10   指定返回记录的数量;
api.domain/user/offset/10  指定返回记录的开始位置;
api.domain/user/animal_type_id/1      指定筛选条件
api.domain/user/page/2/per_page/100   指定第几页，以及每页的记录数;
api.domain/user/sortby/name/order/asc 指定返回结果按照哪个属性排序，以及排序顺序

分页操作

当返回某个资源的列表时，如果要返回的数目特别多，比如 github 的 /users，就需要使用分页分批次按照需要来返回特定数量的结果。

分页的实现会用到上面提到的 url query，通过两个参数来控制要返回的资源结果：

per_page：每页返回多少资源，如果没提供会使用预设的默认值；这个数量也是有一个最大值，不然用户把它设置成一个非常大的值（比如 99999999）也失去了设计的初衷。
page：要获取哪一页的资源，默认是第一页。

6、状态码 Status Code

HTTP 应答中，需要带一个很重要的字段：status code。它说明了请求的大致情况，是否正常完成、需要进一步处理、出现了什么错误，对于客户端非常重要。状态码都是三位的整数，大概分成了几个区间：

2XX：请求正常处理并返回
3XX：重定向，请求的资源位置发生变化
4XX：客户端发送的请求有错误
5XX：服务器端错误

在 HTTP API 设计中，经常用到的状态码以及它们的意义如下表：

针对于状态码，请看此文章：

HTTP常见状态码 - Debug客栈

7、错误处理

如果出错的话，在 response body 中通过 message 给出明确的信息。

比如客户端发送的请求有错误，一般会返回 4XX Bad Request 结果。这个结果很模糊，给出错误 message 的话，能更好地让客户端知道具体哪里有问题，进行快速修改。

如果请求的 JSON 数据无法解析，会返回 Problems parsing JSON；
如果缺少必要的 filed，会返回 422 Unprocessable Entity，除了 message 之外，还通过 errors 给出了哪些 field 缺少了，能够方便调用方快速排错。

基本的思路就是尽可能提供更准确的错误信息：比如数据不是正确的 json，缺少必要的字段，字段的值不符合规定…… 而不是直接说“请求错误”之类的信息。

8、验证及授权

一般来说，让任何人随意访问公开的 API 是不好的做法。验证和授权是两件事情：

验证（Authentication）是为了确定用户是其申明的身份，比如提供账户的密码。不然的话，任何人伪造成其他身份（比如其他用户或者管理员）是非常危险的
授权（Authorization）是为了保证用户有对请求资源特定操作的权限。比如用户的私人信息只能自己能访问，其他人无法看到；有些特殊的操作只能管理员可以操作，其他用户有只读的权限等等

如果没有通过验证（提供的用户名和密码不匹配，token 不正确等），需要返回 401 Unauthorized状态码，并在 body 中说明具体的错误信息；而没有被授权访问的资源操作，需要返回 403 Forbidden 状态码，还有详细的错误信息。

注意：对某些用户未被授权访问的资源操作返回 404 Not Found，目的是为了防止私有资源的泄露（比如黑客可以自动化试探用户的私有资源，返回 403 的话，就等于告诉黑客用户有这些私有的资源，无异于是给黑客提供了方向）。

9、Hypermedia API

RESTful API 最好做到 Hypermedia，即返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。

比如访问 api.github.com，就可以看到 Github API 支持的资源操作。

10、易读的 API 接口文档

API 最终是给人使用的，不管是公司内部，还是公开的 API 都是一样。即使我们遵循了上面提到的所有规范，设计的 API 非常优雅，用户还是不知道怎么使用我们的 API。最后一步，但非常重要的一步是：为你的 API 编写优秀的文档。

注意：对每个请求以及返回的参数给出说明，最好给出一个详细而完整地示例。