网站标题logo怎么做,樱花代码html,东莞横沥镇地图,wordpress 产品相册插件文章目录 引言一、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 响应实… 文章目录 引言一、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 响应实体信息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 APIRepresentational 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 /articlesPOST /articles
避免
GET /getArticlesPOST /createArticle
3.2 使用复数形式表示资源集合
对于资源集合使用复数形式更为直观。
范例
GET /usersGET /users/{id}
避免
GET /userGET /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 响应格式 请求响应传输数据格式JSONJSON数据尽量简单轻量避免多级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?version1自定义 HTTP 头版本控制 例如Accept-version: v1Accept 头版本控制 例如Accept: application/vnd.myapp.v1json
5.2 如何选择
选择版本控制策略时还应考虑对性能的影响尤其是在 Web 服务器上缓存时。 URI 路径版本控制和查询参数版本控制方案都是缓存友好的 因为同一 URI/查询字符串组合每次都指向相同的数据。
自定义 HTTP 头版本控制和Accept 头版本控制机制通常需要其他逻辑来检查自定义标头或 Accept 标头中的值。 在大型环境中使用不同版本的 Web API 的多个客户端可能会在服务器端缓存中生成大量重复数据。 如果客户端应用程序通过实现缓存的代理与 Web 服务器进行通信并且该 代理在当前未在其缓存中保留所请求数据的副本时仅将请求转发到 Web 服务器则此问题可能会变得很严重。
六、数据筛选和分页
6.1 分页和过滤 对集合资源执行的 GET 请求可能返回大量的项。 应将 Web API 设计为限制任何单个请求返回的数据量。 请考虑支持查询字符串指定要检索的最大项数和集合中的起始偏移量。 分页 使用 limit 和 offset 参数或者使用基于游标的分页 过滤 允许客户端指定过滤条件使用查询参数进行过滤
?limit10指定返回记录的数量
?offset10指定返回记录的开始位置。
?page2per_page100statusactive指定第几页以及每页的记录数相应数据的状态。
?sortbynameorderasc指定返回结果按照哪个属性排序以及排序顺序。
?animal_type_id1指定筛选条件总结
设计高质量的 RESTful API 是一个持续的过程。通过遵循本指南中的原则和最佳实践你可以创建出高效、可扩展且易于使用的 API。记住优秀的 API 设计不仅能提高开发效率还能为你的产品或服务创造更大的价值。如要想要获取更多参考范例可以参考Github的API接口Github使用的就是RESTful API希望本文对大家有所帮助。 参考文章
RESTful Web API 设计
HTTP状态码
GitHub REST API 文档
RESTful API 设计指南——阮一峰
