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

相关推荐
葡萄城技术团队19 小时前
REST API 设计最佳实践指南 - 如何用 JavaScript、Node.js 和 Express.js 构建 REST API
restful
麦聪聊数据3 天前
如何使用 QuickAPI 快速连接 MySQL 数据库并发布 RESTful API
数据库·sql·mysql·restful·数据服务
叫我阿柒啊10 天前
从Java全栈到Vue3实战:一次真实面试中的技术探索
java·数据库·spring boot·微服务·typescript·vue3·restful
码熔burning10 天前
Spring Security 深度学习(六): RESTful API 安全与 JWT
安全·spring·restful·springsecurity
代码AI弗森13 天前
AR-LSAT 推理任务全解析:从逻辑推理到类比推理的挑战
人工智能·restful
友莘居士20 天前
springbootr如何调用dolphinshceduler
spring boot·restful·dolphin·shceduler
杨DaB1 个月前
【SpringBoot】Swagger 接口工具
java·spring boot·后端·restful·swagger
楽码1 个月前
在RestFul接口应用Hmac算法
后端·算法·restful
许野平1 个月前
Rust 同步方式访问 REST API 的完整指南
java·网络·rust·restful
ChaITSimpleLove2 个月前
.NET9 使用 OData 协议项目实战
restful·asp.net core·webapi·仓储模式·开放数据协议·分层隔离·.net odata