RESTful API设计指南:构建高效、可扩展和易用的API
文章目录
- 引言
- 一、RESTful API概述
- 1.1 什么是RESTful API
- 1.2 RESTful API的重要性
- 二、RESTful API的基本原则
- 2.1 资源导向设计
- 2.2 HTTP方法的正确使用
- 三、URL设计
- 3.1 使用名词而非动词
- 3.2 使用复数形式表示资源集合
- 四、请求和响应设计
- 4.1 HTTP状态码
- 4.2 响应格式
- 4.2.1 响应实体信息
- 4.2.2 响应列表格式
- 4.2.3 响应分页格式
- 4.3 使用 HATEOAS 导航到相关资源
- 4.4 错误处理
- 五、URI 版本管理
- 5.1 常见的版本控制策略
- 5.2 如何选择
- 六、数据筛选和分页
- 6.1 分页和过滤
- 总结

引言
在当今互联网时代,应用程序和服务之间的通信变得越来越重要。随着移动设备的普及、云计算的发展以及物联网的兴起,我们需要一种灵活、高效且易于理解的方式来设计和实现这些通信接口。RESTful API应运而生,成为了现代软件架构中不可或缺的一部分。
一、RESTful API概述
1.1 什么是RESTful API
RESTful API(Representational State Transfer API),中文翻译过来可以表述为表述性状态转移,是一种基于HTTP协议的网络应用程序接口风格。它遵循REST架构风格的约束条件和原则,以资源为中心,使用标准的HTTP方法(如GET、POST、PUT、DELETE等)来执行操作。RESTful API强调简单性、可扩展性和可读性,使得不同系统之间的通信变得更加直观和高效。
1.2 RESTful API的重要性
RESTful API在现代软件开发中扮演着关键角色,其重要性体现在以下几个方面:
- 标准化:RESTful API遵循统一的设计原则,使得不同开发团队和系统之间的集成变得更加容易。
- 可扩展性:基于资源的设计使得API能够轻松地适应新的需求和功能扩展。
- 简单易用:RESTful API的设计理念使得接口更加直观,降低了开发者的学习成本。
本文旨在提供一个RESTful API设计指南,帮助开发人员构建高效、可扩展和易用的API。我们将介绍RESTful API设计的原则、最佳实践和模式,并提供一些实用的技巧和示例。通过遵循这些指南,开发人员可以设计出易于理解、易于使用和易于维护的API。
二、RESTful API的基本原则
2.1 资源导向设计
资源是RESTful API的核心概念。每个资源都应该有一个唯一的标识符(通常是URL)。设计API时,应该围绕资源而不是动作来组织。例如,一个用户资源可能表示为 /users/{id}
。
2.2 HTTP方法的正确使用
RESTful API利用HTTP方法来表示对资源的操作,常用的有下面几种:
- GET(SELECT):获取资源
- POST(CREATE):创建新资源
- PUT(UPDATE):更新现有资源
- DELETE(DELETE):删除资源
- PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
范例:
GET /users // 获取用户列表
POST /users // 创建新用户
PUT /users/{userId} //获取指定ID的用户信息
PUT /users/{userId} // 更新指定ID的用户信息
DELETE /users/{userId} // 删除指定ID的用户
PATCH /users/{userId} // 更新指定ID用户的部分信息
除此之外还有两种:
- HEAD:获取资源的元数据。
- OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。
三、URL设计
3.1 使用名词而非动词
URL应该表示资源,而不是动作。使用HTTP方法来表示动作。
范例:
- GET /articles
- POST /articles
避免:
- GET /getArticles
- POST /createArticle
3.2 使用复数形式表示资源集合
对于资源集合,使用复数形式更为直观。
范例:
- GET /users
- GET /users/{id}
避免:
- GET /user
- GET /user/{id}
四、请求和响应设计
4.1 HTTP状态码
HTTP状态码是表示请求结果的标准方式。正确使用状态码可以提高API的可读性和一致性。
HTTP状态码范围:
分类 | 分类描述 |
---|---|
1** | 信息,服务器收到请求,需要请求者继续执行操作 |
2** | 成功,操作被成功接收并处理 |
3** | 重定向,需要进一步的操作以完成请求 |
4** | 客户端错误,请求包含语法错误或无法完成请求 |
5** | 服务器错误,服务器在处理请求的过程中发生了错误 |
常用状态码:
200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)。
201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功。
202 Accepted - [*]:表示一个请求已经进入后台排队(异步任务)
204 NO CONTENT - [DELETE]:用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的。
401 Unauthorized - [*]:表示用户没有权限(令牌、用户名、密码错误)。
403 Forbidden - [*] 表示用户得到授权(与401错误相对),但是访问是被禁止的。
404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的。
406 Not Acceptable - [GET]:用户请求的格式不可得(比如用户请求JSON格式,但是只有XML格式)。
410 Gone -[GET]:用户请求的资源被永久删除,且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时,发生一个验证错误。
500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功。
502 Bad Gateway - [*]:服务器作为网关或代理,从上游服务器收到无效响应。
503 Service Unavailable - [*]:服务器当前无法处理请求,可能是由于过载或维护。
504 Gateway Timeout - [*]:服务器作为网关或代理,没有及时从上游服务器收到响应。
根据具体情况选择适当的状态码,避免滥用200状态码来表示所有情况。
4.2 响应格式
请求响应传输数据格式:JSON,JSON数据尽量简单轻量,避免多级JSON的出现。
4.2.1 响应实体信息
{code: 200,msg: "success",data: {entity: {id: 1,name: "XXX",code: "XXX"}}
}
4.2.2 响应列表格式
{code: 200,msg: "success",data: {records: {entity: {id: 1,name: "XXX",code: "XXX"},entity: {id: 2,name: "XXX",code: "XXX"}}}
}
4.2.3 响应分页格式
{"msg": "success","code": 200,"data": {"current": 0,"records": [{id: 1,name: "XXX",code: "H001"},{id: 2,name: "XXX",code: "H001"}],"size": 5,"total": 2}
}
分析:
data
: 数据主体,包含了分页信息和记录列表。
current
: 当前页码,这里的值为 0,表示第一页(具体按照公司规范)。records
: 记录列表,包含了当前页的所有记录,每个记录包含id
、name
和code
字段。size
: 每页大小,这里的值为 5,表示每页最多显示5条记录。total
: 总记录数,这里的值为 2,表示一共有2条记录。
4.3 使用 HATEOAS 导航到相关资源
REST 背后的主要动机之一是它应能够导航整个资源集,而无需事先了解 URI 方案。 每个 HTTP GET 请求应通过响应中包含的超链接返回查找与所请求的对象直接相关的资源所需的信息,还应为它提供描述其中每个资源提供的操作的信息。 此原则称为 HATEOAS 或作为应用程序状态引擎的超文本。
由于当前没有如何为 HATEOAS 原则建模的任何通用标准,因此此部分的示例仅作为一个可能的参考。
例如,若要处理订单与客户之间的关系,可以在订单的表示形式中包含链接,用于指定下单客户可以执行的操作。 下面是可能的表示形式:
{"orderID":3,"productID":2,"quantity":4,"orderValue":16.60,"links":[{"rel":"customer","href":"https://adventure-works.com/customers/3","action":"GET","types":["text/xml","application/json"]},{"rel":"customer","href":"https://adventure-works.com/customers/3","action":"PUT","types":["application/x-www-form-urlencoded"]},{"rel":"customer","href":"https://adventure-works.com/customers/3","action":"DELETE","types":[]},{"rel":"self","href":"https://adventure-works.com/orders/3","action":"GET","types":["text/xml","application/json"]}]
}
在此示例中,
links
数组包含一组链接。 每个链接表示可对相关实体执行的操作。 每个链接的数据包含关系 (“customer”)、URI (https://adventure-works.com/customers/3
)、HTTP 方法和支持的 MIME 类型。 这是客户端应用程序在调用操作时所需的全部信息。
links
数组还包含有关已检索的资源本身的自引用信息。 这些链接包含关系 self。
4.4 错误处理
错误响应应包含:
- HTTP状态码
- 错误消息
- 错误代码(可选)
- 详细说明(可选)
例如:
{"code": "50x","message": "The provided email address is invalid"
}
五、URI 版本管理
5.1 常见的版本控制策略
- URI 路径版本控制
例如:/api/v1/users
- 查询参数版本控制
例如:/api/users?version=1
- 自定义 HTTP 头版本控制
例如:Accept-version: v1
- Accept 头版本控制
例如:Accept: application/vnd.myapp.v1+json
5.2 如何选择
选择版本控制策略时,还应考虑对性能的影响,尤其是在 Web 服务器上缓存时。 URI 路径版本控制和查询参数版本控制方案都是缓存友好的,
因为同一 URI/查询字符串组合每次都指向相同的数据。
自定义 HTTP 头版本控制和Accept 头版本控制机制通常需要其他逻辑来检查自定义标头或 Accept 标头中的值。 在大型环境中,使用不同版本的
Web API 的多个客户端可能会在服务器端缓存中生成大量重复数据。 如果客户端应用程序通过实现缓存的代理与 Web 服务器进行通信,并且该
代理在当前未在其缓存中保留所请求数据的副本时,仅将请求转发到 Web 服务器,则此问题可能会变得很严重。
六、数据筛选和分页
6.1 分页和过滤
对集合资源执行的 GET 请求可能返回大量的项。 应将 Web API 设计为限制任何单个请求返回的数据量。 请考虑支持查询字符串指定要检索的最大项数和集合中的起始偏移量。
-
分页:
- 使用 limit 和 offset 参数
- 或者使用基于游标的分页
-
过滤:
- 允许客户端指定过滤条件
- 使用查询参数进行过滤
?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100&status=active:指定第几页,以及每页的记录数,相应数据的状态。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?animal_type_id=1:指定筛选条件
总结
设计高质量的 RESTful API 是一个持续的过程。通过遵循本指南中的原则和最佳实践,你可以创建出高效、可扩展且易于使用的 API。记住,优秀的 API 设计不仅能提高开发效率,还能为你的产品或服务创造更大的价值。如要想要获取更多参考范例,可以参考Github的API接口,Github使用的就是RESTful API,希望本文对大家有所帮助😊。
参考文章:
RESTful Web API 设计
HTTP状态码
GitHub REST API 文档
RESTful API 设计指南——阮一峰
相关文章:

RESTful API设计指南:构建高效、可扩展和易用的API
文章目录 引言一、RESTful API概述1.1 什么是RESTful API1.2 RESTful API的重要性 二、RESTful API的基本原则2.1 资源导向设计2.2 HTTP方法的正确使用 三、URL设计3.1 使用名词而非动词3.2 使用复数形式表示资源集合 四、请求和响应设计4.1 HTTP状态码4.2 响应格式4.2.1 响应实…...
npm下载的依赖包版本号怎么看
npm下载的依赖包版本号怎么看 版本号一般分三个部分,主版本号、次版本号、补丁版本号。 主版本号:一般依赖包发生重大更新时,主版本号才回发生变化,如Vue2.x到Vue3.x。次版本号:当依赖包中发生了一些小变化ÿ…...
css前端面试题
1.什么是css盒子模型? 盒子模型包含了元素内容(content)、内边距(padding)、边框(border)、外边距(margin)几个要素。 标准盒子模型和IE盒子模型的区别在于其对元素的w…...

Vue从零到实战
💝💝💝欢迎来到我的博客,很高兴能够在这里和您见面!希望您在这里可以感受到一份轻松愉快的氛围,不仅可以获得有趣的内容和知识,也可以畅所欲言、分享您的想法和见解。 非常期待和您一起在这个小…...

【Chatgpt大语言模型医学领域中如何应用】
随着人工智能技术 AI 的不断发展和应用,ChatGPT 作为一种强大的自然语言处理技术,无论是 自然语言处理、对话系统、机器翻译、内容生成、图像生成,还是语音识别、计算机视觉等方面,ChatGPT 都有着广泛的应用前景。特别在临床医学领…...
ES6 正则的扩展(十九)
1. 正则表达式字面量改进 特性:在 ES6 中,正则表达式字面量允许在字符串中使用斜杠(/)作为分隔符。 用法:简化正则表达式的书写。 const regex1 /foo/; const regex2 /foo/g; // 全局搜索2. u 修饰符(U…...

<数据集>钢铁缺陷检测数据集<目标检测>
数据集格式:VOCYOLO格式 图片数量:1800张 标注数量(xml文件个数):1800 标注数量(txt文件个数):1800 标注类别数:6 标注类别名称:[crazing, patches, inclusion, pitted_surface, rolled-in_scale, scr…...
Kafka系列之:Kafka存储数据相关重要参数理解
Kafka系列之:Kafka存储数据相关重要参数理解 一、log.segment.bytes二、log.retention.bytes三、日志段四、log.retention.check.interval.ms五、数据底层文件六、index、log、snapshot、timeindex、leader-epoch-checkpoint、partition.metadata一、log.segment.bytes 参数lo…...

Template execution failed: ReferenceError: name is not defined
问题 我们使用了html-webpack-plugin(webpack)进行编译html,导致的错误。 排查结果 连接地址 html-webpack-plugin版本低(2.30.1),html模板里面不能有符号,注释都不行 // var reg new RegExp((^|&)${name}([^&…...

CVE-2024-24549 Apache Tomcat - Denial of Service
https://lists.apache.org/thread/4c50rmomhbbsdgfjsgwlb51xdwfjdcvg Apache Tomcat输入验证错误漏洞,HTTP/2请求的输入验证不正确,会导致拒绝服务,可以借助该漏洞攻击服务器。 https://mvnrepository.com/artifact/org.apache.tomcat.embed/…...

Linux下如何安装配置Graylog日志管理工具
Graylog是一个开源的日志管理工具,可以帮助我们收集、存储和分析大量的日志数据。它提供了强大的搜索、过滤和可视化功能,可以帮助我们轻松地监控系统和应用程序的运行情况。 在Linux系统下安装和配置Graylog主要包括以下几个步骤: 准备安装…...

「MQTT over QUIC」与「MQTT over TCP」与 「TCP 」通信测试报告
一、结论 在实车5G测试中「MQTT Over QUIC」整体表现优于「TCP」,可在系统架构升级时采用MQTT Over QUIC替换原有的TCP通讯;从实现原理上基于QUIC比基于TCP在弱网、网络抖动导致频繁重连场景延迟更低。 二、测试方案 网络类型:实车5G、实车…...
获取磁盘剩余容量-----c++
获取磁盘剩余容量 #include <filesystem>struct DiskSpaceInfo {double total;double free;double available; };DiskSpaceInfo getDiskSpace(const std::string& path) {std::filesystem::space_info si std::filesystem::space(path);DiskSpaceInfo info;info.…...

AI算法24-决策树C4.5算法
目录 决策树C4.5算法概述 决策树C4.5算法简介 决策树C4.5算法发展历史 决策树C4.5算法原理 信息熵(Information Entropy) 信息增益(Information Gain) 信息增益比(Gain Ratio) 决策树C4.5算法改进 …...

【云原生】Prometheus整合Alertmanager告警规则使用详解
目录 一、前言 二、Altermanager概述 2.1 什么是Altermanager 2.2 Altermanager使用场景 三、Altermanager架构与原理 3.1 Altermanager使用步骤 3.2 Altermanager工作机制 3.3 Altermanager在Prometheus中的位置 四、Altermanager部署与接入Prometheus 4.1 Altermana…...

C++ :友元类
友元类的概念和使用 (1)将类A声明为B中的friend class后,则A中所有成员函数都成为类B的友元函数了 (2)代码实战:友元类的定义和使用友元类是单向的 (3)友元类是单向的,代码实战验证 互为友元类 (1)2个类可以互为友元类,代码实战…...
【整理了一些关于使用swoole使用的解决方案】
目录 如何监控和分析 Swoole 服务器的性能瓶颈? 在进行 Swoole 服务器性能优化时,有哪些常见的错误和陷阱需要避免? 除了 Swoole,还有哪些 PHP 框架或技术可以用于构建高并发的 Web 应用? Swoole 同步请求在高并发…...
python selenium4 EdgeDriver动态页面爬取
截止至2024.7.16 chrome浏览器最新版本为126.0.6478.127 但对应的chromeDriver版本都低于此版本,因此,转用Edge浏览器 说明:仅记录自己使用过程中用到的一些代码和感受,看具体情况不定期更新。 selenium官方文档 1、安装selen…...
【一次记一句:SQL】从 information_schema.TABLES中查询数据库表中记录数据量
有时候,一张千万数据量的表,使用 count(*) 统计记录数,查不动。可以使用下述SQL来试试: SELECT CONCAT(table_schema, ., table_name) AS "Table Name", table_rows AS "Number of Rows", CONCAT(ROUND(data…...

NXP i.MX8系列平台开发讲解 - 3.19 Linux TTY子系统(二)
专栏文章目录传送门:返回专栏目录 Hi, 我是你们的老朋友,主要专注于嵌入式软件开发,有兴趣不要忘记点击关注【码思途远】 目录 1. Linux 串口驱动 1.1 Uart 驱动注册流程 1.2 uart 操作函数 1.3 line discipline 2. Linux tty应用层使用…...

wordpress后台更新后 前端没变化的解决方法
使用siteground主机的wordpress网站,会出现更新了网站内容和修改了php模板文件、js文件、css文件、图片文件后,网站没有变化的情况。 不熟悉siteground主机的新手,遇到这个问题,就很抓狂,明明是哪都没操作错误&#x…...

练习(含atoi的模拟实现,自定义类型等练习)
一、结构体大小的计算及位段 (结构体大小计算及位段 详解请看:自定义类型:结构体进阶-CSDN博客) 1.在32位系统环境,编译选项为4字节对齐,那么sizeof(A)和sizeof(B)是多少? #pragma pack(4)st…...

(二)TensorRT-LLM | 模型导出(v0.20.0rc3)
0. 概述 上一节 对安装和使用有个基本介绍。根据这个 issue 的描述,后续 TensorRT-LLM 团队可能更专注于更新和维护 pytorch backend。但 tensorrt backend 作为先前一直开发的工作,其中包含了大量可以学习的地方。本文主要看看它导出模型的部分&#x…...
【android bluetooth 框架分析 04】【bt-framework 层详解 1】【BluetoothProperties介绍】
1. BluetoothProperties介绍 libsysprop/srcs/android/sysprop/BluetoothProperties.sysprop BluetoothProperties.sysprop 是 Android AOSP 中的一种 系统属性定义文件(System Property Definition File),用于声明和管理 Bluetooth 模块相…...
2023赣州旅游投资集团
单选题 1.“不登高山,不知天之高也;不临深溪,不知地之厚也。”这句话说明_____。 A、人的意识具有创造性 B、人的认识是独立于实践之外的 C、实践在认识过程中具有决定作用 D、人的一切知识都是从直接经验中获得的 参考答案: C 本题解…...

C# 求圆面积的程序(Program to find area of a circle)
给定半径r,求圆的面积。圆的面积应精确到小数点后5位。 例子: 输入:r 5 输出:78.53982 解释:由于面积 PI * r * r 3.14159265358979323846 * 5 * 5 78.53982,因为我们只保留小数点后 5 位数字。 输…...

HashMap中的put方法执行流程(流程图)
1 put操作整体流程 HashMap 的 put 操作是其最核心的功能之一。在 JDK 1.8 及以后版本中,其主要逻辑封装在 putVal 这个内部方法中。整个过程大致如下: 初始判断与哈希计算: 首先,putVal 方法会检查当前的 table(也就…...

推荐 github 项目:GeminiImageApp(图片生成方向,可以做一定的素材)
推荐 github 项目:GeminiImageApp(图片生成方向,可以做一定的素材) 这个项目能干嘛? 使用 gemini 2.0 的 api 和 google 其他的 api 来做衍生处理 简化和优化了文生图和图生图的行为(我的最主要) 并且有一些目标检测和切割(我用不到) 视频和 imagefx 因为没 a…...

人机融合智能 | “人智交互”跨学科新领域
本文系统地提出基于“以人为中心AI(HCAI)”理念的人-人工智能交互(人智交互)这一跨学科新领域及框架,定义人智交互领域的理念、基本理论和关键问题、方法、开发流程和参与团队等,阐述提出人智交互新领域的意义。然后,提出人智交互研究的三种新范式取向以及它们的意义。最后,总结…...
动态 Web 开发技术入门篇
一、HTTP 协议核心 1.1 HTTP 基础 协议全称 :HyperText Transfer Protocol(超文本传输协议) 默认端口 :HTTP 使用 80 端口,HTTPS 使用 443 端口。 请求方法 : GET :用于获取资源,…...