首页 > 其他分享 >RESTful API 设计规范与最佳实践

RESTful API 设计规范与最佳实践

时间:2024-08-09 10:18:17浏览次数:13  
标签:API GET URI zoos 设计规范 POST RESTful 资源

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

标签:API,GET,URI,zoos,设计规范,POST,RESTful,资源
From: https://www.cnblogs.com/chatlin/p/18350286

相关文章

  • 使用Python和Flask框架实现简单的RESTful API
    目录环境准备创建Flask应用运行Flask应用测试API注意事项在当今的Web开发领域,RESTfulAPI因其简洁性和高效性而备受欢迎。本文将引导你使用Python的Flask框架来创建一个简单的RESTfulAPI,用于增删改查(CRUD)用户信息。环境准备在开始之前,请确保你的Python环境中已经安......
  • CH2~CH5 DataStream API基础
    一个Flink程序,就是对DataStream进行各种转换。基本上由以下几部分构成接下来分别从执行环境、数据源、转换操作、输出四大部分,介绍DataStreamAPI。导入ScalaDataStreamApiimportorg.apache.flink.streaming.api.scala._CH-5DataStreamAPI基础一、执行环境1.1创建执......
  • 2024年最新免费AI大模型API汇总及国内大模型使用教程(附代码)
    免费大模型API一览大模型免费版本免费限制控制台(api_key等)API文档讯飞星火大模型spark-litetokens:总量无限;QPS:2;(每秒发送的请求数)有效期:不限访问链接访问链接百度千帆大模型平台ERNIE-Speed-8KRPM=300,TPM=300000(RPM是每分钟请求数(RequestsPerMinute),TPM是指每分......
  • 如何进行 API 管理?为什么 Apifox 是管理 API 的推荐方案?
    本文来聊聊API管理这个话题。在当今这个互联互通的网络里,API就像是不同软件系统之间的"翻译官",让它们能够相互交流、共享数据。想象一下,如果没有API,我们的应用程序就像是孤岛,无法获取外部的信息和服务。所以说,API的重要性怎么强调都不为过!但是,随着API数量的激增和复杂度的......
  • 一个基于 vue 的强大表单和高性能表格组件,简洁API设计,支持虚拟树,列拖拽,懒加载,快捷
    前言在现代Web应用开发中,表单和表格是两个核心组件,它们对于数据展示和用户交互至关重要。然而,现有的解-决方案往往存在一些痛点,如不够灵活、性能问题、以及难以实现复杂功能等。这些问题限制了开发者的创造力,也影响了用户体验。为了解决这些痛点,开发者需要一款功能强大、灵活......
  • 主打一个免费:英智LLM推理API,主流大模型API任你选!
     人工智能(AI)技术的飞速发展已经成为各行各业的关键驱动力,尤其是大语言模型(LLM)正在成为推动下一波技术创新浪潮的颠覆性力量。开发者如何享受LLM带来的红利,创造出优秀的应用?实践证明,使用大语言模型API,可以有事半功倍的效果! 部署过大模型的小伙伴应该都清楚,在本地部署L......
  • vue中axios二次封装【简洁、附代码】+api解耦
    reference:https://www.bilibili.com/video/BV1my421h7hK/?share_source=copy_web&vd_source=334dbcc5ec1e90276a3fca594c89e11e下一篇:继axios二次封装后跨域问题解决——配置代理、环境变量文章目录一、axios请求接口1下载2引入3使用二、axios二次封装1.下......
  • 零一万物完成数亿美元融资;OpenAI 引入 API 结构化输出功能
    ......
  • ArcGIS API for JavaScript 3.x 到 4.x 的升级手册
    众所周知,3.x版本主要是构建二维地图,且基本不会再添加新功能;而4.x版本主要是构建于三维地图,与3.x相比并不是简单的升级,基本上就是重写了。所以当我们需要把API从3.x升级到4.x时,应用程序基本上是需要重写的,这里将对API升级过程中涉及到的相关变动进行记录与描述。以下......
  • 比肩DRF,轻量级、快速且强大的 API 开发:探索 DN 框架
    Django-Ninja框架,简称DN框架,是一个用于快速构建API的现代化框架。它基于Django构建,但专注于简洁性和性能,使用Pydantic进行数据验证,使得开发体验更加流畅和高效。为什么选择DN框架?DN框架结合了Django的稳定性和Pydantic的强大数据处理能力,适用于需要快速迭代和高......