RESTful API 设计规范与最佳实践

本文由 ChatMoney团队出品

一、URI规范

1. URI全部使用小写字母；

2. 使用中划线（-）分隔单词，而不是下划线（_）；

3. 对参数列表进行编码；

4. URI中的名词应使用复数形式，代表资源集合；

5. 网址中只能包含名词，不能有动词，特殊情况除外。名词通常与数据库的表格名对应。

资源集合与单个资源：

URI可以表示资源集合或单个资源。例如：

• 资源集合：/zoos（所有动物园），/zoos/1/animals（id为1的动物园中所有动物）

• 单个资源：/zoos/1（id为1的动物园）

避免层级过深的URI：

避免使用过多的层级，例如GET /zoos/1/areas/3/animals/4。可以使用查询参数代替路径中的实体导航，例如GET /animals?zoo=1&area=3。

二、版本

将API的版本号放入URI中，例如：

• https://api.example.com/v1/zoos

三、Request

HTTP方法：

• GET：查询资源，幂等；

• POST：创建新资源，非幂等；

• PUT：更新单个资源，幂等；

• DELETE：删除资源，幂等；

• HEAD：获取资源的元数据；

• OPTIONS：获取关于资源的信息；

• PATCH：更新资源的部分字段，幂等。

复杂查询：

可以使用以下参数进行复杂查询：

• 过滤条件：例如?type=1&age=16；

• 排序：例如?sort=age&order=asc；

• 投影：例如?whitelist=id,name,email；

• 分页：例如?page=2&per_page=100。

状态码：

服务器向用户返回的状态码和提示信息，例如200 OK（GET请求成功），201 CREATED（POST/PUT/PATCH请求成功创建资源）等。

URI失效：

对于失效的API，返回404 Not Found或410 Gone；对于迁移的API，返回301重定向。

四、Response

• 不要在响应体中进行包装；

• 根据不同的HTTP方法，成功处理后的数据格式分别为：GET（单个对象/集合），POST（新增成功的对象），PUT/PATCH（更新成功的对象），DELETE（空）。

五、错误处理

• 发生错误时，不要返回2xx响应码；

• 正确设置HTTP状态码，不要自定义；

• 返回错误信息时，使用“error”作为键名，错误描述作为键值。

六、其他

• API的身份认证应使用OAuth 2.0框架；

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

• 对于复杂的接口，根据业务代码确定使用POST还是PUT。如果接口产生的结果幂等，使用PUT，否则使用POST。

关于我们

本文由ChatMoney团队出品，ChatMoney专注于AI应用落地与变现，我们提供全套、持续更新的AI源码系统与可执行的变现方案，致力于帮助更多人利用AI来变现，欢迎进入ChatMoney获取更多AI变现方案！