Featured image of post Restful API 设计指北
Debuginn

Restful API 设计指北

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

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

使用 HTTPS 协议

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

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

API 地址和版本问题

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

1

https://api.debuginn.com

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

1

https://debuginn.com/api/

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

1
2
3
4

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

Schema 响应数据模式

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

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

使用正确的 Method

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

1
2
3
4
5

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

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

1
2

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

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

过滤信息

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

筛选操作

1
2
3
4
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：要获取哪一页的资源，默认是第一页。

状态码 Status Code

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

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

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

状态码LABEL解释
200OK请求成功接收并处理，一般响应中都会有 body
201Created请求已完成，并导致了一个或者多个资源被创建，最常用在 POST 创建资源的时候
202Accepted请求已经接收并开始处理，但是处理还没有完成。一般用在异步处理的情况，响应 body 中应该告诉客户端去哪里查看任务的状态
204No Content请求已经处理完成，但是没有信息要返回，经常用在 PUT 更新资源的时候（客户端提供资源的所有属性，因此不需要服务端返回）。如果有重要的 metadata，可以放到头部返回
301Moved Permanently请求的资源已经永久性地移动到另外一个地方，后续所有的请求都应该直接访问新地址。服务端会把新地址写在 Location 头部字段，方便客户端使用。允许客户端把 POST 请求修改为 GET。
304Not Modified请求的资源和之前的版本一样，没有发生改变。用来缓存资源，和条件性请求（conditional request）一起出现
307Temporary Redirect目标资源暂时性地移动到新的地址，客户端需要去新地址进行操作，但是不能修改请求的方法。
308Permanent Redirect和 301 类似，除了客户端不能修改原请求的方法
400Bad Request客户端发送的请求有错误（请求语法错误，body 数据格式有误，body 缺少必须的字段等），导致服务端无法处理
403Forbidden服务器端接收到并理解客户端的请求，但是客户端的权限不足。比如，普通用户想操作只有管理员才有权限的资源。
404Not Found客户端要访问的资源不存在，链接失效或者客户端伪造 URL 的时候会遇到这个情况
405Method Not Allowed服务端接收到了请求，而且要访问的资源也存在，但是不支持对应的方法。服务端必须返回Allow头部，告诉客户端哪些方法是允许的
415Unsupported Media Type服务端不支持客户端请求的资源格式，一般是因为客户端在Content-Type或者Content-Encoding中申明了希望的返回格式，但是服务端没有实现。比如，客户端希望收到xml返回，但是服务端支持Json
429Too Many Requests客户端在规定的时间里发送了太多请求，在进行限流的时候会用到
500Internal Server Error服务器内部错误，导致无法完成请求的内容
503Service Unavailable服务器因为负载过高或者维护，暂时无法提供服务。服务器端应该返回 Retry-After 头部，告诉客户端过一段时间再来重试

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

错误处理

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

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

如果请求的 JSON 数据无法解析，会返回Problems parsing JSON；

如果缺少必要的 filed，会返回422 Unprocessable Entity，除了 message 之外，还通过errors给出了哪些 field 缺少了，能够方便调用方快速排错。

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

验证及授权

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

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

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

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

Hypermedia API

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

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

易读的 API 接口文档

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

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

参考资料