RESTful接口规范参考

介绍

  • REST(Representational State Transfe),一种架构设计风格,而不是强制标准,主要用于客户端与服务端接口规范;
  • 在现代的软件开发中,RESTful API已经成为应用程序之间通信的重要桥梁,互联网公司也更倾向于实践此风格;
  • 核心是面向资源,每个网址代表一种资源(URI),具有解释性;
  • 行为(GET / POST / PUT / PATCH / DELETE)与资源(URI)分离,更加轻量;
  • 数据描述简单,使⽤JSON、XML、PROTOBUFFER即可全覆盖,主要使⽤JSON;

设计规范

  • 安全

API与⽤户的通信协议,⼀般使⽤HTTP协议,更安全情况下使⽤HTTPS;

  • 域名

应该尽量将API部署在专⽤域名之下,比如api.example.com

  • 版本

在每个API对应的URL中,应有⼀个版本号,以便将来服务升级后,所有版本的客户端可以正常使用,例如/api/v1/xxx

  • 命名

核心是面向资源,每个网址代表一种资源,网址中尽量使用名词,避免动词。

资源对应的是数据库中的集合,所以名词尽量使用复数,除非没有合适的复数形式(如 weather)。

  • 请求方式
请求方式 示例 说明
GET /teams/{id} 读取
POST /teams 新建,通常带有 Body
PUT /teams/{id} 更新,全量更新,通常带有 Body
PATCH /teams/{id} 更新,部分更新,通常带有 Body
DELETE /teams/{id} 删除

行业参考

  • 佳明接口文档

https://developers.strava.com/playground/#/

最佳实践

GET

读取。

示例:

basic 复制代码
get /teams # 获取车队列表
get /teams/list # 同上,获取车队列表
get /teams?page=1&size=10&search=武汉 # 分页搜索列表

get /teams/{id} # 获取车队id为{id}的详情
get /teams/{id}/detail # 同上,获取车队id为{id}的详情

get /teams/{id}/members # 获取车队id为{id}下的成员列表

POST

新建。

一个参数可放在路径参数,多个参数必须放到 body 中。

示例:

basic 复制代码
post /teams/{name} # 新建车队,仅有名称

post /teams # 新建车队
# body
{
"name": "武汉车队",
"number": 8888
}

PUT

更新。

put 通常指全部更新,patch 通常指部分更新,一搬支持 put 即可。

示例:

basic 复制代码
put /teams/{id} # 修改车队id为{id}的信息
# body
{
"id": 123,
"name": "武汉车队Plus",
"number": 9999
}

DELETE

删除。

示例:

basic 复制代码
delete /teams/{id} # 删除车队id为{id}的车队
相关推荐
追逐时光者4 小时前
精选 4 款基于 .NET 开源、功能强大的 Windows 系统优化工具
后端·.net
TF男孩4 小时前
ARQ:一款低成本的消息队列,实现每秒万级吞吐
后端·python·消息队列
AAA修煤气灶刘哥5 小时前
别让Redis「歪脖子」!一次搞定数据倾斜与请求倾斜的捉妖记
redis·分布式·后端
AAA修煤气灶刘哥5 小时前
后端人速藏!数据库PD建模避坑指南
数据库·后端·mysql
你的人类朋友6 小时前
什么是API签名?
前端·后端·安全
昵称为空C7 小时前
SpringBoot3 http接口调用新方式RestClient + @HttpExchange像使用Feign一样调用
spring boot·后端
架构师沉默8 小时前
设计多租户 SaaS 系统,如何做到数据隔离 & 资源配额?
java·后端·架构
RoyLin8 小时前
TypeScript设计模式:适配器模式
前端·后端·node.js
该用户已不存在9 小时前
Mojo vs Python vs Rust: 2025年搞AI,该学哪个?
后端·python·rust
Moonbit9 小时前
MoonBit 正式加入 WebAssembly Component Model 官方文档 !
前端·后端·编程语言