本文由 ChatMoney团队出品
一、URI规范
-
URI全部使用小写字母；
-
使用中划线（-）分隔单词，而不是下划线（_）；
-
对参数列表进行编码；
-
URI中的名词应使用复数形式，代表资源集合；
-
网址中只能包含名词，不能有动词，特殊情况除外。名词通常与数据库的表格名对应。
资源集合与单个资源：
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中，例如：
三、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变现方案！