RESTful接口与http协议状态表述

简介: 该文介绍了RESTful风格API的好处和设计原则。RESTful API以资源为中心,通过HTTP方法(GET, POST, PUT, DELETE)表示操作,利用状态码反馈操作结果。它简化了客户端与服务端的交互,提供了一种通用规范,减少沟通成本。设计要点包括:URI描述资源,HTTP方法体现操作,使用标准HTTP状态码,GET不改变数据,使用复数名词,支持复杂资源关系,可选实现HATEOAS,以及接口版本管理。

一、本文大纲

   RESTful风格API的好处

   RESTful API的设计风格

二、RESTful风格API的好处

API(Application Programming Interface),顾名思义:是一组编程接口规范,客户端与服务端通过请求响应进行数据通信。REST(Representational State Transfer)表述性状态传递,决定了接口的形式与规则。RESTful是基于http方法的API设计风格,而不是一种新的技术.

   看Url就知道要什么资源

   看http method就知道针对资源干什么

   看http status code就知道结果如何

对接口开发提供了一种可以广泛适用的规范,为前端后端交互减少了接口交流的口舌成本,是约定大于配置的体现。通过下面的设计,大家来理解一下这三句话。

   当然也不是所有的接口,都能用REST的形式来表述。在实际工作中,灵活运用,我们用RESTful风格的目的是为大家提供统一标准,避免不必要的沟通成本的浪费,形成一种通用的风格。就好比大家都知道:伸出大拇指表示“你很棒“的意思,绝大部分人都明白,因为你了解了这种风格习惯。但是不排除有些地区伸出大拇指表示其他意思,就不适合使用!

二、RESTful API的设计风格

2.1、RESTful是面向资源的(名词)

REST 通过 URI 暴露资源时,会强调不要在 URI 中出现动词。比如:

不符合REST的接口URI 符合REST接口URI 功能

GET /api/getDogs/{id} GET /api/dogs/{id} 获取一个小狗狗

GET /api/getDogs GET /api/dogs 获取所有小狗狗

GET /api/addDogs POST /api/dogs 添加一个小狗狗

GET /api/editDogs/{id} PUT /api/dogs/{id} 修改一个小狗狗

GET /api/deleteDogs/{id} DELETE /api/dogs/{id} 删除一个小狗狗

2.2、用HTTP方法体现对资源的操作(动词)

   GET : 获取、读取资源

   POST : 添加资源

   PUT : 修改资源

   DELETE : 删除资源

   实际上,这四个动词实际上就对应着增删改查四个操作,这就利用了HTTP动词来表示对资源的操作。

2.3. HTTP状态码

通过HTTP状态码体现动作的结果,不要自定义

   200 OK  

   400 Bad Request  

   500 Internal Server Error

在 APP 与 API 的交互当中,其结果逃不出这三种状态:

   所有事情都按预期正确执行完毕 - 成功

   APP 发生了一些错误 – 客户端错误(如:校验用户输入身份证,结果输入的是军官证,就是客户端输入错误)

   API 发生了一些错误 – 服务器端错误(各种编码bug或服务内部自己导致的异常)

这三种状态与上面的状态码是一一对应的。如果你觉得这三种状态,分类处理结果太宽泛,http-status code还有很多。建议还是要遵循KISS(Keep It Stupid and Simple)原则,上面的三种状态码完全可以覆盖99%以上的场景。这三个状态码大家都记得住,而且非常常用,多了就不一定了。

2.4. Get方法和查询参数不应该改变数据

改变数据的事交给POST、PUT、DELETE

2.5. 使用复数名词

/dogs 而不是 /dog

2.6. 复杂资源关系的表达

GET /cars/711/drivers/ 返回 使用过编号711汽车的所有司机

GET /cars/711/drivers/4 返回 使用过编号711汽车的4号司机

2.7. 高级用法:HATEOAS

HATEOAS:Hypermedia as the Engine of Application State 超媒体作为应用状态的引擎。

RESTful API最好做到HATEOAS,即返回结果中提供链接,连向其他API方法,使得用户不查文档,也知道下一步应该做什么。比如,当用户向api.example.com的根目录发出请求,会得到这样一个文档。

   {"link": {

     "rel":   "collection https://www.example.com/zoos",

     "href":  "https://api.example.com/zoos",

     "title": "List of zoos",

     "type":  "application/vnd.yourformat+json"

   }}

上面代码表示,文档中有一个link属性,用户读取这个属性就知道下一步该调用什么API或者可以调用什么API了。

2.8. 资源过滤、排序、选择和分页的表述

2.9. 版本化你的API

强制性增加API版本声明,不要发布无版本的API。如:/api/v1/blog

面向扩展开放,面向修改关闭:也就是说一个版本的接口开发完成测试上线之后,我们一般不会对接口进行修改,如果有新的需求就开发新的接口进行功能扩展。这样做的目的是:当你的新接口上线后,不会影响使用老接口的用户。如果新接口目的是替换老接口,也不要在v1版本原接口上修改,而是开发v2版本接口,并声明v1接口废弃!


相关文章
|
25天前
|
安全 API 持续交付
阿里云云效产品使用问题之如何从流水线访问内网平台的HTTP接口
云效作为一款全面覆盖研发全生命周期管理的云端效能平台,致力于帮助企业实现高效协同、敏捷研发和持续交付。本合集收集整理了用户在使用云效过程中遇到的常见问题,问题涉及项目创建与管理、需求规划与迭代、代码托管与版本控制、自动化测试、持续集成与发布等方面。
|
26天前
|
安全 网络协议 网络安全
IP代理的三大协议:HTTP、HTTPS与SOCKS5的区别
**HTTP代理**适用于基本网页浏览,简单但不安全;**HTTPS代理**提供加密,适合保护隐私;**SOCKS5代理**灵活强大,支持TCP/UDP及认证,适用于绕过限制。选择代理协议应考虑安全、效率及匿名需求。
|
21小时前
|
API 数据安全/隐私保护 开发者
Web 开发新风尚!Python RESTful API 设计与实现,让你的接口更懂开发者心!
【7月更文挑战第23天】Python的RESTful API设计在Web开发中流行,提升效率与体验。REST强调HTTP方法(GET, POST, PUT, DELETE)操作资源。使用Flask框架可快速实现API,如管理用户信息。示例代码展示如何创建、读取、更新和删除用户,通过不同HTTP方法和URL路径。实际应用中,增加验证、错误处理和权限控制可增强API的安全性和稳定性。安装Flask后,可运行代码测试API功能。
16 6
|
1天前
|
安全 API 网络架构
Python RESTful API设计新篇章,打造高效、易用、安全的Web服务接口,你准备好了吗?
【7月更文挑战第22天】在数字化转型中,RESTful API借助Python的Flask和Django REST Framework,提供高效、易用和安全的接口设计。Flask示例展示了简洁的CRUD操作,Swagger等工具增进API文档的易用性,而HTTPS、JWT和输入验证确保安全性。Python RESTful API设计涉及效率、可用性和安全,是不断进化的Web服务接口的关键。准备好踏上这一新篇章了吗?一起探索,创造卓越!
|
1天前
|
缓存 网络协议 算法
从零开始掌握HTTP协议:全面详解1.0、1.1和2.0
大家好!我是小米,今天带大家深入探讨互联网基础——HTTP协议。从HTTP/1.0到HTTP/1.1,再到HTTP/2.0,它们是如何发展的,解决了哪些问题,有哪些显着区别?通过这这篇文章,你将全面了解这些协议的变革和优化,掌握关键技术点,提升开发效率。快来一起学习吧!
10 1
|
8天前
|
消息中间件 API 数据库
在微服务架构中,每个服务通常都是一个独立运行、独立部署、独立扩展的组件,它们之间通过轻量级的通信机制(如HTTP/RESTful API、gRPC等)进行通信。
在微服务架构中,每个服务通常都是一个独立运行、独立部署、独立扩展的组件,它们之间通过轻量级的通信机制(如HTTP/RESTful API、gRPC等)进行通信。
|
25天前
|
安全 网络安全 数据安全/隐私保护
深入理解HTTP协议:工作原理与安全性
【6月更文挑战第28天】HTTP是互联网基础协议,用于浏览器与服务器通信。基于请求-响应模型,无状态且可扩展。但其明文传输、缺乏身份验证和数据完整性校验导致安全问题。HTTPS 加入SSL/TLS,提供加密、身份验证和完整性校验,保障网络安全。了解HTTP原理和安全至关重要。
|
10天前
|
网络协议 安全 Python
我们将使用Python的内置库`http.server`来创建一个简单的Web服务器。虽然这个示例相对简单,但我们可以围绕它展开许多讨论,包括HTTP协议、网络编程、异常处理、多线程等。
我们将使用Python的内置库`http.server`来创建一个简单的Web服务器。虽然这个示例相对简单,但我们可以围绕它展开许多讨论,包括HTTP协议、网络编程、异常处理、多线程等。
|
18天前
|
JSON 数据格式
MysbatisPlus-核心功能-IService开发基础业务接口,MysbatisPlus_Restful风格,新增@RequestBody指定是为了接收Json数据的,使用swagger必须注解
MysbatisPlus-核心功能-IService开发基础业务接口,MysbatisPlus_Restful风格,新增@RequestBody指定是为了接收Json数据的,使用swagger必须注解
|
25天前
|
存储 API
什么是RESTful接口风格
什么是RESTful接口风格
13 0