本文由 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变现方案!
标签:API,GET,URI,zoos,设计规范,POST,RESTful,资源 From: https://www.cnblogs.com/chatlin/p/18350286