Restful API 接口设计标准及规范
Restful API 接口设计标准以及规范
RESTful概念
理解和评估以网络为基础的应用软件的架构设计,得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。" 如果一个架构符合REST的约束条件和原则,我们就称它为RESTful架构。
REST本身并没有创造新的技术、组件或服务,而隐藏在RESTful背后的理念就是使用Web的现有特征和能力, 更好地使用现有Web标准中的一些准则和约束。虽然REST本身受Web技术的影响很深, 但是理论上REST架构风格并不是绑定在HTTP上,只不过目前HTTP是唯一与REST相关的实例。 所以我们这里描述的REST也是通过HTTP实现的REST。
RestfulAPI 导图
理解RESTful
要理解RESTful架构,需要理解Representational State Transfer这个词组到底是什么意思,它的每一个词都有些什么涵义。我们围绕资源展开讨论,从资源的定义、获取、表述、关联、状态变迁等角度,列举一些关键概念并加以解释。
- 资源与URI
- 统一资源接口
- 资源的表述
- 资源的链接
- 状态的转移
资源与URI
URI 表示资源,资源一般对应服务器端领域模型中的实体类
- URI 是地址也是资源
- URI里边带上版本号、后缀来区分表述格式
- 必备约定
- 用名词、不用动词
- 层级结构明确、用/来表示
- 用?用来过滤资源
统一资源接口
标准HTTP方法包含:GET、POST、PUT、DELETE、Patch,他们的使用功能如下列表所示
Get方法执行流程原理如下所示
Put 方法执行流程图如下所示
安全性和幂等性
- 1、安全性:不会改变资源状态,可以理解为只读的;
- 2、幂等性:执行1次和执行N次,对资源状态改变的效果是等价的。
接口 | 安全性 | 幂等性 |
---|---|---|
GET | √ | √ |
POST | × | × |
PUT | × | √ |
DELETE | × | √ |
安全性和幂等性均不保证反复请求能拿到相同的response。以 DELETE 为例,第一次DELETE返回200表示删除成功,第二次返回404提示资源不存在,这是允许的。
资源的表述
什么是资源?什么是表述?
就本质而言,任何足够重要并被引用的事物都可以是资源。如果你的用户“想要建立指向它的超文本链接,指出或者反对关于它的断言,获取或者缓存它的表述,共另外的表述引用它的全部或者部分,给它增加注释信息,或者对它执行某些操作”,(源自《万维网的架构》),你都应该将它定义为资源。
每个资源必须拥有URL,在web上,我们使用URL来为每个资源提供一个全球唯一的地址,将一个事物赋以URL,它就会成为一个资源。
石榴可以是一个资源,但是你不可能通过互联网传输它,数据库中的一条记录可以是一个资源,并且可以通过互联网传输。
当客户端对一个资源发起一个Get请求的时候,服务器会以一种有效的方式提供一个采集了资源信息的文档作为回应。这种资源信息的文档就是一种表述,一种以机器可读的方式对资源当前的状态进行说明
资源有多重表述
一个资源可以有多种表述。比如,有的资源可以有整体概括性的表述,也可以有面面俱到的详细表述,又或者可能以JSON格式或者XML格式来表述同一个资源。
资源的连接
我们知道REST是使用标准的HTTP方法来操作资源的,但仅仅因此就理解成带CURD的Web数据库架构就太过于简单了。
这种反模式忽略了一个核心概念:"超媒体即应用状态引擎(hypermedia as the engine of application state)"。 超媒体是什么?
当你浏览Web网页时,从一个连接跳到一个页面,再从另一个连接跳到另外一个页面,就是利用了超媒体的概念:把一个个把资源链接起来.
要达到这个目的,就要求在表述格式里边加入链接来引导客户端。在《RESTful Web Services》一书中,作者把这种具有链接的特性成为连通性。下面我们具体来看一些例子。
下面展示的是github获取某个组织下的项目列表的请求,可以看到在响应头里边增加Link头告诉客户端怎么访问下一页和最后一页的记录。 而在响应体里边,用url来链接项目所有者和项目地址。
上面的例子展示了如何使用超媒体来增强资源的连通性。很多人在设计RESTful架构时,使用很多时间来寻找漂亮的URI,而忽略了超媒体。所以,应该多花一些时间来给资源的表述提供链接,而不是专注于"资源的CRUD"。
状态的转移
访问一个网站,就代表了客户端和服务器的一个互动过程。在这个过程中,势必涉及到数据和状态的变化;
互联网通信协议HTTP协议,是一个无状态协议。这意味着,所有的状态都保存在服务器端。因此,如果客户端想要操作服务器,必须通过某种手段,让服务器端发生"状态转化"(State Transfer)。而这种转化是建立在表现层之上的,所以就是"表现层状态转化";
客户端用到的手段,只能是HTTP协议。具体来说,就是HTTP协议里面,四个表示操作方式的动词:GET、POST、PUT、DELETE。它们分别对应四种基本操作:GET用来获取资源,POST用来新建资源(也可以用于更新资源),PUT用来更新资源,DELETE用来删除资源;
博主GitHub地址
关注公众号不迷路
Restful API 接口设计标准及规范的更多相关文章
- RESTful API接口文档规范小坑
希望给你3-5分钟的碎片化学习,可能是坐地铁.等公交,积少成多,水滴石穿,谢谢关注. 前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问 ...
- RESTful API设计原则与规范
RESTful API设计原则与规范 一.背景与基础概念 2 二.RESTful API应遵循的原则 3 1.协议(Protocol) 3 2.域名(ROOT URL) 3 3.版本(Versioni ...
- SpringMVC Restful api接口实现
[前言] 面向资源的 Restful 风格的 api 接口本着简洁,资源,便于扩展,便于理解等等各项优势,在如今的系统服务中越来越受欢迎. .net平台有WebAPi项目是专门用来实现Restful ...
- API接口通讯参数规范(2)
针对[API接口通讯参数规范]这篇文章留下的几个问题进行探讨. 问题1 试想一下,如果一个http请求返回一个500给我们,那我们是不是都不用看详情都知道该次请求发生了什么?这正是一个标准的结果码意义 ...
- Java 调用Restful API接口的几种方式--HTTPS
摘要:最近有一个需求,为客户提供一些Restful API 接口,QA使用postman进行测试,但是postman的测试接口与java调用的相似但并不相同,于是想自己写一个程序去测试Restful ...
- 初识restful api接口
一.restful api接口举例 实现功能 传统方式 restful方式 url HTTP方法 url HTTP方法 查询 /user/query?name=knyel GET /user?name ...
- 整合swagger2生成Restful Api接口文档
整合swagger2生成Restful Api接口文档 swagger Restful文档生成工具 2017-9-30 官方地址:https://swagger.io/docs/specificati ...
- 使用Flask设计带认证token的RESTful API接口
大数据时代 Just a record. 使用Flask设计带认证token的RESTful API接口[翻译] 上一篇文章, 使用python的Flask实现一个RESTful API服务器端 简 ...
- Spring Boot入门系列(二十)快速打造Restful API 接口
spring boot入门系列文章已经写到第二十篇,前面我们讲了spring boot的基础入门的内容,也介绍了spring boot 整合mybatis,整合redis.整合Thymeleaf 模板 ...
随机推荐
- 【ACwing 98】分形之城——分形
(题面来自ACwing) 城市的规划在城市建设中是个大问题. 不幸的是,很多城市在开始建设的时候并没有很好的规划,城市规模扩大之后规划不合理的问题就开始显现. 而这座名为 Fractal 的城市设想了 ...
- 「有数可据」选择IT行业的1000个理由!
这你要我编 我也编不出一千个呀 现如今转行IT 还需要1000个理由吗? 不 不需要的 一个就好 10月初 CSDN博主「有数可据」 发布了 2020年10月国内程序员薪资情况 他本人是这样说的☟ ...
- 【2020.11.30提高组模拟】剪辣椒(chilli)
剪辣椒(chilli) 题目描述 在花园里劳累了一上午之后,你决定用自己种的干辣椒奖励自己. 你有n个辣椒,这些辣椒用n-1条绳子连接在一起,任意两个辣椒通过用若干个绳子相连,即形成一棵树. 你决定分 ...
- Nacos windows下 ERROR Nacos failed to start, please see
如果是windows 本地启动 直接到你本地\nacos\bin下 用cmd 启动即可 startup.cmd -m standalone 看见它你就算是 完成 了 直接访问下本的的端口 h ...
- Linux之【安装系统后的调优和安全设置】
关闭SElinux功能 •修改配置文件使其永远生效 第一种修改方法vi vi /etc/sysconfig/selinuc 或者 vi /etc/selinux/config修改: SELINUX=d ...
- Centos7 之间的文件拷贝
环境: 内网了两台cenots7主机 scp命令 scp [参数] [原路径] [目标路径] scp -P 22022 /home/file.war root@192.168.253.172:/hom ...
- [翻译自官方]什么是RDB和AOF? 一文了解Redis持久化!
概述 本文提供Redis持久化技术说明, 建议所有Redis用户阅读. 如果您想更深入了解Redis持久性原理机制和底层持久性保证, 请参考文章 揭秘Redis持久化: http://antire ...
- pom文件中<dependencies>和<dependencyManagement>的区别
在父pom中,如果使用了<dependencies>标签,那么在该标签体中的所有jar包,即使子工程中没有写这些依赖,依旧会引用. 如果使用了<dependencyManagemen ...
- PyQt(Python+Qt)学习随笔:model/view架构中支持QListView列表中展示图标的两种方法
老猿Python博文目录 专栏:使用PyQt开发图形界面Python应用 老猿Python博客地址 在QListView列表视图中的项不但可以展示文字,也可以展示图标和复选框,同时可以指定项是否可以拖 ...
- urllib.request.urlopen(req).read().decode解析http报文报“utf-8 codec can not decode”错处理
老猿前期执行如下代码时报"'utf-8' codec can't decode byte"错,代码及错误信息如下: >>> import urllib.reque ...