一个简约可行的 REST API 规范

1.背景

一个稍大的系统必然由多个不同的模块组成，每个模块的后台服务一般由不同的开发人员负责开发维护。不同模块对外提供的接口命名风格、协议结构和错误码等不一致，会增加使用方（如客户端）不必要的理解和使用成本。

后台接口一般以 REST API 形式对外提供服务，为了提升接口可维护性与使用者的体验，公司或团队应制定对外接口的统一规范。此外，规范化的接口设计可以提高软件的可扩展性和可维护性，减少代码冗余和开发时间。

2.接口设计

URL 设计

1. 用 HTTP 方法操作资源。

使用 HTTP 五种方法 POST，GET，PUT/PATCH，DELETE 提供 CRUD 功能。其中 PUT 更新整个资源，PATCH 更新资源部分信息。

2. 用复数名词表示集合。

如果 URL 表示的资源是个一个集合应该使用名词。

比如一个论坛有很多帖子，表示帖子的 URL 应该是 https://mysite.com/posts 而不是 https://mysite.com/post。

3. 明确版本划分。

划分 API 版本，常见的做法是在 URL Path 中加入版本标识。

/v1/employees
/v2/employees

协议

1. 使用 JSON 作为发送和接收数据的格式。

2. 使用统一的回包格式，将实际数据包装在 data 字段中。

{
  "code": 0,
  "msg": "ok",
  "data":{}
}

分页接口回包 data 结构包含 total 总记录数，结构如下：

"data": {
  "data":[],
  "total":100
}

命名风格

1. JSON 键命名使用 camelCase 风格。

{
  "thisPropertyIsAnIdentifier": "identifier value"
}

2. URL Path 使用连字符分隔单词，Query 使用下划线分隔单词。

GET https://api.example.com/favorite-teachers?first_name=john&last_name=doe

文档

1. 为接口提供 Swagger 说明文档，并包含清晰的协议字段说明。

3.通用错误码

业务错误码 1 开头的 1XXXX 为通用错误码，其他错误码，不同模块服务自行与调用方约定。

以下是一些常见的错误码。

10000	入参有误
10001	Token 非法
10002	请求超时
10003	记录未找到
10004	DB 写入失败
10005	DB 更新失败
10006	DB 查询失败
10007	DB 删除失败
10008	JSON 序列化失败
10009	JSON 反序列化失败

---

参考文献

REST API 最佳实践_恋喵大鲤鱼的博客
Google JSON Style Guide