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中,例如:

三、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变现方案!

相关推荐
hello_ejb321 小时前
聊聊Spring AI的RetrievalAugmentationAdvisor
人工智能·spring·restful
Foyo Designer3 天前
【 <二> 丹方改良:Spring 时代的 JavaWeb】之 Spring Boot 中的国际化:支持多语言的 RESTful API
java·spring boot·redis·后端·spring·缓存·restful
神奇侠20246 天前
快速入手-基于Django-rest-framework的自身组件权限认证(九)
django·restful
庆 、9 天前
Django REST framework 源码剖析-认证器详解(Authentication)
后端·python·django·framework·restful·authentication
Foyo Designer12 天前
【 <二> 丹方改良:Spring 时代的 JavaWeb】之 Spring Boot 中的 RESTful API 设计:从上手到骨折
spring boot·spring·restful·spring mvc·async·crossorigin
boring_student14 天前
CUL-CHMLFRP启动器 windows图形化客户端
前端·人工智能·python·5g·django·自动驾驶·restful
Foyo Designer20 天前
【 <二> 丹方改良:Spring 时代的 JavaWeb】之 Spring MVC 的崛起:从 Struts 到 Spring 的演进
struts·spring·servlet·mvc·javaweb·restful
轻口味21 天前
Vue.js 与 RESTful API 集成之使用 Axios 请求数据
前端·vue.js·restful
八九燕来21 天前
Django REST Framework中的序列化器类和视图类
django·sqlite·restful
微风灬浮尘23 天前
Java程序开发之Spring Boot快速入门:5分钟搭建RESTful API
java·spring boot·restful·java入门