规范设计RESTful API

如何理解 RESTful 架构？

特点：

• 每一个 URI 代表一种资源
• 客户端与服务器之间，传递这种资源的某种表现层
• 客户端通过四个 HTTP 动词对服务端资源进行操作

资源

所谓”资源”，就是网络上的一个实体，或者说是网络上的一个具体信息。

可以用一个 URI（统一资源定位符）指向它，每种资源对应一个特定的 URI。

表现层

把”资源”具体呈现出来的形式，叫做它的”表现层”.

URI 只代表资源的实体，不代表它的形式。应该在 HTTP 请求的头信息中用 Accept 和 Content-Type 字段指定，这两个字段才是对”表现层”的描述。

状态转化

如果客户端想要操作服务器，必须通过某种手段，让服务器端发生”状态转化”（State Transfer）。而这种转化是建立在表现层之上的，所以就是”表现层状态转化”。

是 HTTP 协议里面，四个表示操作方式的动词：GET、POST、PUT、DELETE。

RESTful API 设计规范

1. 协议的规范：

与服务器的通信总是使用 HTTP 协议

2. 域名：

应该吧 API 部署到专属域名上

如：https://api.kilic.site

若是 API 为简单 API，可以放在主域名下：https://kilic.site/api

3. 版本：

将 API 的版本号放入 URL。

如：https://api.kilic.site/v1;

4. 路径：

每一种路径代表一种资源，所以资源的设计应该是名词（错误示范：我一直都是用动词短语做的〒 ▽ 〒），所用的名词往往与数据库的表格名对应。

数据库的表一般有多个字段，所以这里的名词需要是负数形式，比如：

https://api.kilic.site/v1/consumers

https://api.kilic.site/v1/stores

5. HTTP 动词：

动词使用 HTTP 请求头的 Method 字段进行表示：

• GET ——> SELECT
• POST ——> GREATE
• PUT ——> UPDATE （客户端提供完整资源）
• PATCH ——> UPDATE（客户端提供改变的属性）
• DELETE ——> DELETE （删除资源）

6. 资源过滤：

通过 GET 方法的参数指定过滤条件：

1
2
3

?id=1
?limit=10&offset=1
?sortby=username

7. 状态码

8. 错误处理

对 4XX 系列的状态码，应该在返回信息中封装 error 作为键名

1
2
3
4

{
  "status": 404,
  "error": "NOT FOUND"
}

9. 服务器返回规范

服务器向用户返回的结果应该符合以下规范。

1
2
3
4
5
6

GET /collection：返回资源对象的列表（数组）
GET /collection/resource：返回单个资源对象
POST /collection：返回新生成的资源对象
PUT /collection/resource：返回完整的资源对象
PATCH /collection/resource：返回完整的资源对象
DELETE /collection/resource：返回一个空文档

其他：

API 的身份认证应该使用OAuth 2.0框架。可以看我的一篇 JWT 文章：JWT 原理与 Nestjs 的 JWT 方案

服务器返回的数据格式，应该尽量使用 JSON，避免使用 XML。

参考资源

理解 RESTful 架构

RESTful API 设计指南