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

相关推荐
许野平2 天前
Rust: Warp RESTful API 如何得到客户端IP?
tcp/ip·rust·restful·ip地址
百锦再2 天前
Web后端开发技术:RESTful 架构详解
前端·架构·restful
Milujem_Ta4 天前
每日奇难怪题(持续更新)
后端·restful
_.Switch5 天前
构建高效 Python Web API:RESTful 设计与 GraphQL 实践
开发语言·前端·后端·python·restful·graphql
_.Switch6 天前
Python Web 应用的部署与运维
运维·开发语言·前端·python·restful·graphql
许野平13 天前
Rust:Restful API 服务程序开发详述
rust·restful·tokio·warp·hyper
无理 Java16 天前
【实战指南】RESTful 从入门到精通(Spring Boot)
java·spring boot·后端·spring·面试·restful·restful api
无理 Java17 天前
【Spring Boot 实战】统一数据返回格式的最佳实践:构建稳定的RESTful API(实战篇)
java·spring boot·后端·面试·restful·数据返回
李少兄20 天前
Spring MVC RESTful API - 修改状态接口示例
spring·mvc·restful
爱掉发的小李20 天前
Docker 的基本概念和优势,以及在应用程序开发中的实际应用
java·前端·后端·docker·容器·eureka·restful