理解 RESTful API 设计规范
RESTful是目前最流行的API设计规范,它是用于Web数据接口的设计。从字面可以看出,他是Rest式的接口,所以我们先了解下什么是Rest。
REST与技术无关,它代表的是一种软件架构风格,REST它是 Representational State Transfer的简称,中文的含义是: "表征状态转移" 或 "表现层状态转化"。它是基于HTTP、URI、XML、JSON等标准和协议,支持轻量级、跨平台、跨语言的架构设计。
一. 理解为什么要使用RESTful API设计规范?
在很久以前,工作时间长的同学肯定经历过使用velocity语法来编写html模板代码,也就是说我们的前端页面放在服务器端那边进行编译的,更准确的可以理解为 "前后端没有进行分离",那么在那个时候,页面、数据及模板渲染操作都是放在服务器端进行的,但是这样做有一个很大的缺点是: 后期维护比较麻烦,前端开发人员还必须掌握velocity相关的语法。因此为了解决这个问题慢慢就出现了前后端分离的思想: 即后端负责数据接口, 前端负责数据渲染, 前端只需要请求下api接口拿到数据,然后再将数据显示出来。因此后端开发人员需要设计api接口,因此为了统一规范: 社区就出现了 RESTful API 规范,其实该规范很早就有的,只是最近慢慢流行起来,RESTful API 可以通过一套统一的接口为所有web相关提供服务,实现前后端分离。
二. Rest设计原则
那么怎么样可以设计成REST的架构规范呢? 需要符合如下的一些原则:
1. 每一个URI代表一种资源;
2. 同一种资源有多种表现形式(xml/json);
3. 所有的操作都是无状态的。
4. 规范统一接口。
5. 返回一致的数据格式。
6. 可缓存(客户端可以缓存响应的内容)。
符合上述REST原则的架构方式被称作为 RESTful 规范。
理解为什么所有的操作需要无状态呢?
http请求本身是无状态的,它是基于 client-server 架构的,客户端向服务器端发的每一次请求都必须带有充分的信息能够让服务器端识别到,请求的一些信息通常会包含在URL的查询参数中或header中,服务器端能够根据请求的各种参数, 不需要保存客户端的状态, 直接将数据返回给客户端。无状态的优点是:可以大大提高服务器端的健状性和可扩展性。客户端可以通过token来标识会话状态。从而可以让该用户一直保持登录状态。
理解规范统一的接口
Rest接口约束定义为: 资源识别;请求动作;响应信息; 它表示通过uri表示出要操作的资源,通过请求动作(http method)标识要执行的操作,通过返回的状态码来表示这次请求的执行结果。
可能看上面的解释还不够理解,下面我通过自己的理解来解释下上面的具体含义; 比如说,我在未使用Rest规范之前,我们可能有 增删改查 等接口,因此我们会设计出类似这样的接口: /xxx/newAdd (新增接口), /xxx/delete(删除接口), /xxx/query (查询接口), /xxx/uddate(修改接口)等这样的。增删改查有四个不同的接口,维护起来可能也不好,因此如果我们现在使用Restful规范来做的话,对于开发设计来说可能就只需要一个接口就可以了,比如设计该接口为 /xxx/apis 这样的一个接口就可以了,然后请求方式(method)有 GET--查询(从服务器获取资源); POST---新增(从服务器中新建一个资源); PUT---更新(在服务器中更新资源),DELETE---删除(从服务器删除资源),PATCH---部分更新(从服务器端更新部分资源) 等这些方式来做,也就是说我们使用RESTful规范后,我们的接口就变成了一个了,要执行增删改查操作的话,我们只需要使用不同的请求动作(http method)方式来做就可以了,然后服务器端返回的数据也可以是相同的,只是我们前端会根据状态码来判断请求成功或失败的状态值来判断。具体有那些状态码我们下面会讲解到。
理解返回一致的数据格式
服务器端返回的数据格式可以是XML、或json. 或者直接返回状态码的方式。比如返回错误的格式json数据如下:
{
"code": 401,
"status": "error",
"message": '用户没有权限',
"data": null
}
返回正确的数据格式的json数据一般可以为如下:
{
"code": 200,
"status": "success",
"data": [{
"userName": "tugenhua",
"age": 31
}]
}
三. URL及参数设计规范
1. uri设计规范
1) uri末尾不需要出现斜杠/
2) 在uri中使用斜杠/是表达层级关系的。
3) 在uri中可以使用连接符-, 来提升可读性。
比如 http://xxx.com/xx-yy 比 http://xxx.com/xx_yy中的可读性更好。
4) 在uri中不允许出现下划线字符_.
5) 在uri中尽量使用小写字符。
6) 在uri中不允许出现文件扩展名. 比如接口为 /xxx/api, 不要写成 /xxx/api.php 这样的是不合法的。
7) 在uri中使用复数形式。
具体可以看:(https://blog.restcase.com/7-rules-for-rest-api-uri-design/)
在RESTful架构中,每个uri代表一种资源,因此uri设计中不能使用动词,只能使用名词,并且名词中也应该尽量使用复数形式。使用者应该使用相应的http动词 GET、POST、PUT、PATCH、DELETE等操作这些资源即可。
那么在我们未使用RESTful规范之前,我们是如下方式来定义接口的,形式是不固定的,并且没有统一的规范。比如如下形式:
http://xxx.com/api/getallUsers; // GET请求方式,获取所有的用户信息
http://xxx.com/api/getuser/1; // GET请求方式,获取标识为1的用户信息
http://xxx.com/api/user/delete/1 // GET、POST 删除标识为1的用户信息
http://xxx.com/api/updateUser/1 // POST请求方式 更新标识为1的用户信息
http://xxx.com/api/User/add // POST请求方式,添加新的用户
如上我们可以看到,在未使用Restful规范之前,接口形式是不固定的,没有统一的规范,下面我们来看下使用RESTful规范的接口如下,两者之间对比下就可以看到各自的优点了。
http://xxx.com/api/users; // GET请求方式 获取所有用户信息
http://xxx.com/api/users/1; // GET请求方式 获取标识为1的用户信息
http://xxx.com/api/users/1; // DELETE请求方式 删除标识为1的用户信息
http://xxx.com/api/users/1; // PATCH请求方式,更新标识为1的用户部分信息
http://xxx.com/api/users; // POST请求方式 添加新的用户
如上我们可以看到,增删改成我们都是使用同一个api接口,只是请求的方式 GET(查询)、POST(新增)、DELETE(删除)、PACTH(部分更新)来代表的是增删改查操作的方式。然后开发获取到该请求的header头部信息,就可以知道是什么方式来请求数据的了。
2. HTTP请求规范
GET (SELECT): 查询;从服务器取出资源.
POST(CREATE): 新增; 在服务器上新建一个资源。
PUT(UPDATE): 更新; 在服务器上更新资源(客户端提供改变后的完整资源)。
PATCH(UPDATE): 更新;在服务器上更新部分资源(客户端提供改变的属性)。
DELETE(DELETE): 删除; 从服务器上删除资源。
3. 参数命名规范
参数推荐采用下划线命名的方式。比如如下demo:
http://xxx.com/api/today_login // 获取今天登录的用户。
http://xxx.com/api/today_login&sort=login_desc // 获取今天登录的用户、登录时间降序排序。
四. http状态码相关的
状态码范围
客户端的每一次请求, 服务器端必须给出回应,回应一般包括HTTP状态码和数据两部分。
1xx: 信息,请求收到了,继续处理。
2xx: 代表成功. 行为被成功地接收、理解及采纳。
3xx: 重定向。
4xx: 客户端错误,请求包含语法错误或请求无法实现。
5xx: 服务器端错误.
2xx 状态码
200 OK [GET]: 服务器端成功返回用户请求的数据。
201 CREATED [POST/PUT/PATCH]: 用户新建或修改数据成功。
202 Accepted 表示一个请求已经进入后台排队(一般是异步任务)。
204 NO CONTENT -[DELETE]: 用户删除数据成功。
4xx状态码
400:Bad Request - [POST/PUT/PATCH]: 用户发出的请求有错误,服务器不理解客户端的请求,未做任何处理。
401: Unauthorized; 表示用户没有权限(令牌、用户名、密码错误)。
403:Forbidden: 表示用户得到授权了,但是访问被禁止了, 也可以理解为不具有访问资源的权限。
404:Not Found: 所请求的资源不存在,或不可用。
405:Method Not Allowed: 用户已经通过了身份验证, 但是所用的HTTP方法不在它的权限之内。
406:Not Acceptable: 用户的请求的格式不可得(比如用户请求的是JSON格式,但是只有XML格式)。
410:Gone - [GET]: 用户请求的资源被转移或被删除。且不会再得到的。
415: Unsupported Media Type: 客户端要求的返回格式不支持,比如,API只能返回JSON格式,但是客户端要求返回XML格式。
422:Unprocessable Entity: 客户端上传的附件无法处理,导致请求失败。
429:Too Many Requests: 客户端的请求次数超过限额。
5xx 状态码
5xx 状态码表示服务器端错误。
500:INTERNAL SERVER ERROR; 服务器发生错误。
502:网关错误。
503: Service Unavailable 服务器端当前无法处理请求。
504:网关超时。
五. 统一返回数据格式
RESTful规范中的请求应该返回统一的数据格式。对于返回的数据,一般会包含如下字段:
1) code: http响应的状态码。
2) status: 包含文本, 比如:'success'(成功), 'fail'(失败), 'error'(异常) HTTP状态响应码在500-599之间为 'fail'; 在400-499之间为 'error', 其他一般都为 'success'。 对于响应状态码为 1xx, 2xx, 3xx 这样的可以根据实际情况可要可不要。
当status的值为 'fail' 或 'error'时,需要添加 message 字段,用于显示错误信息。
3) data: 当请求成功的时候, 返回的数据信息。 但是当状态值为 'fail' 或 'error' 时,data仅仅包含错误原因或异常信息等。
返回成功的响应JSON格式一般为如下:
{
"code": 200,
"status": "success",
"data": [{
"userName": "tugenhua",
"age": 31
}]
}
返回失败的响应json格式为如下:
{
"code": 401,
"status": "error",
"message": '用户没有权限',
"data": null
}
理解 RESTful API 设计规范的更多相关文章
- rest-framework 序列化格式Restful API设计规范
理解RESTful架构 Restful API设计指南 理解RESTful架构 越来越多的人开始意识到,网站即软件,而且是一种新型的软件. 这种"互联网软件"采用客户端/服务器模式 ...
- Restful API设计规范及实战【说的比较清楚了】
Restful API设计规范及实战 Restful API的概念在此就不费口舌了,博友们网上查哈定义文章很多,直入正题吧: 首先抛出一个问题:判断id为 用户下,名称为 使命召唤14(COD14 ...
- RESTful api 设计规范
该仓库整理了目前比较流行的 RESTful api 设计规范,为了方便讨论规范带来的问题及争议,现把该文档托管于 Github,欢迎大家补充!! Table of Contents RESTful A ...
- Restful API设计规范及实战
Restful API的概念在此就不费口舌了,博友们网上查哈定义文章很多,直入正题吧: 首先抛出一个问题:判断id为 用户下,名称为 使命召唤14(COD14) 的产品是否存在(话说我还是很喜欢玩类似 ...
- 理解Restful api的意义
RESTful API 只是API的设计规范或者是一套设计理论. 单就URL和Method这两个点,你可以这样理解: URL 是用来唯一标示一个互联网资源的,而 Method 是用来标识当前请求对该资 ...
- 我是如何根据豆瓣api来理解Restful API设计的
1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思.它是在Roy Fielding博士论文首次提出.REST本身没有创造新的技术.组件 ...
- PHPer的项目RESTful API设计规范是怎样的?
RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计. 什么是RESTful RESTful是一种软件设计风格, 主要用于客户端与服务端交互的软件. 一般来说RESTful ...
- RESTful API设计规范总结
RESTful 是目前最流行的 API 设计规范,用于 Web 数据接口的设计. 它的大原则容易把握,但是细节不容易做对.本文总结 RESTful 的设计细节,介绍如何设计出易于理解和使用的 API. ...
- 理解RESTful Api设计
REST REST(REpresentational State Transfer)是 Roy Fielding 博士于 2000 年在他的博士论文中提出来的一种软件架构风格(一组架构约束条件和原则) ...
随机推荐
- oracle函数 trunc(x[,y])
[功能]返回x按精度y截取后的值 [参数]x,y,数字型表达式,如果y不为整数则截取y整数部分,如果y>0则截取到y位小数,如果y小于0则截取到小数点向左第y位,小数前其它数据用0表示. [返回 ...
- es6 中let与const的简析
1.let 它的作用类似于var,用来声明变量,但是所声明的变量,只在let命令所在的代码块内有效. if(true){ ; let b = ; } document.write(a); docume ...
- 模板—点分治A(容斥)(洛谷P2634 [国家集训队]聪聪可可)
洛谷P2634 [国家集训队]聪聪可可 静态点分治 一开始还以为要把分治树建出来……• 树的结构不发生改变,点权边权都不变,那么我们利用刚刚的思路,有两种具体的分治方法.• A:朴素做法,直接找重心, ...
- javascript 变量的提升
下面是一个关于全局和局部作用域的问题 var a = 123; function f(){ alert(a); var a = 1; alert(a); } f(); 大家第一眼看到后都会认为第一次a ...
- springboot 实现 aop
pom.xml 导入 springboot aop 依赖 <dependency> <groupId>org.springframework.boot</groupId& ...
- jQuery中的siblings()的用法
siblings 英文翻译 兄; 弟; 姐; 妹; 的意思 siblings()用于查找当前元素的同胞元素,就是拿到当前元素的兄弟节点(不包括自己). 给当前元素设置新的样式,并删除当前元 ...
- 2019-10-7-dotnet-Framework-源代码-·-ScrollViewer
title author date CreateTime categories dotnet Framework 源代码 · ScrollViewer lindexi 2019-10-07 13:15 ...
- Roslyn 静态分析
本文告诉大家如何使用 Roslyn 分析代码 首先创建一个项目,项目使用.net Framework 4.6.2 ,控制台项目.然后需要安装一些需要的库 Nuget 安装 打开 Nuget 安装下面两 ...
- 如何查看 Python 全部内置变量和内置函数?
https://jingyan.baidu.com/article/7082dc1c071649e40a89bdb8.html Python 解释器内置了一些常量和函数,叫做内置常量(Built-in ...
- linux scull 函数open 方法
open 方法提供给驱动来做任何的初始化来准备后续的操作. 在大部分驱动中, open 应当 进行下面的工作: 检查设备特定的错误(例如设备没准备好, 或者类似的硬件错误 如果它第一次打开, 初始化设 ...