REST,即Representational State Transfer的缩写。直接翻译的意思是"表现层状态转化"。它是一种互联网应用程序的API设计理念:URL定位资源,用HTTP动词(GET,POST,DELETE,DETC)描述操作。
移动互联网的发展,前端设备层出不穷(手机、平板、桌面电脑、其他专用设备......),因此,必须有一种统一的机制,方便不同的前端设备与后端进行通信,于是RESTful诞生了,它可以通过一套统一的接口为 Web,iOS和Android提供服务。
即统一资源标识符,服务器上每一种资源,比如文档、图像、视频片段、程序 都由一个通用资源标识符(Uniform Resource Identifier, 简称"URI")进行定位。
常用的HTTP动词有下面五个
1、GET(SELECT):从服务器取出资源(一项或多项)。
2、POST(CREATE):在服务器新建一个资源。
3、PUT(UPDATE):在服务器更新资源(客户端提供改变后的完整资源)。
4、PATCH(UPDATE):在服务器更新资源(客户端提供改变的属性)。
5、DELETE(DELETE):从服务器删除资源。
服务器上每一种资源,比如一个文件,一张图片,一部电影,都有对应的url地址,如果我们的客户端需要对服务器上的这个资源进行操作,就需要通过http协议执行相应的动作来操作它,比如进行获取,更新,删除。
1.客户端-服务器:通过将用户UI与数据存储分开,我们可以简化服务器组件来提高跨多个平台的用户界面的可移植性并提高可伸缩性。 它可以比表现成前后端分离的思想。
2.无状态:从客户端到服务器的每个请求都必须包含理解请求所需的所有信息,并且不能利用服务器上任何存储的上下文。 这表示你应该尽可能的避免使用session,由客户端自己标识会话状态。(token)
3.规范接口:REST接口约束定义:资源识别; 请求动作; 响应信息; 它表示通过uri标出你要操作的资源
,通过请求动作(http method)标识要执行的操作,通过返回的状态码来表示这次请求的执行结果。
4.可缓存: 缓存约束要求将对请求的响应中的数据隐式或显式标记为可缓存或不可缓存。如果响应是可缓存的,则客户端缓存有权重用该响应数据以用于以后的等效请求。 它表示get请求响应头中应该表示有是否可缓存的头(Cache-Control)
资源的描述构成了uri,它一般有以下约束:
1.使用名词。如 user, student, class
http://api.com/class-management/students
http://api.com/device-management/managed-devices/{device-id}
http://api.com/user-management/users/
http://api.com/user-management/users/{id}
2.http method对应不同的请求动作(数据库或者业务逻辑)GET
:查询操作:
HTTP GET /devices?startIndex=0&size=20
HTTP GET /configurations?startIndex=0&size=20
HTTP GET /devices/{id}/configurations
HTTP GET /devices/{id}POST
:新增操作:
HTTP POST /devicePUT
更新操作(代表更新一个实体的所有属性)
HTTP PUT /devices/{id}PATCH
部分更新(代表更新一个尸体的部分属性)由于有的浏览器兼容性问题,一般推荐使用put
HTTP PATCH /devices/{id}DELETE
删除操作
HTTP DELETE /devices/{id}
3.使用连字符( - )而不是(_)来提高URI的可读性
http://api.com/inventory-management/managed-entities/{id}/install-script-location //更易读
http://api.com/inventory_management/managed_entities/{id}/install_script_location //更容易出错
4.在URI中使用小写字母
http://api.com/my-folder/my-doc
5.不要使用文件扩展名 文件扩展名看起来很糟糕,不会增加任何优势。删除它们也会减少URI的长度。没理由保留它们。
http://api.com/device-management/managed-devices.xml/ 不要使用它/
http://api.com/device-management/managed-devices/ *这是正确的URI * /
6.使用查询组件过滤URI集合
很多时候,我们会遇到需要根据某些特定资源属性对需要排序,过滤或限制的资源集合的要求。为此,请不要创建新的API - 而是在资源集合API中启用排序,过滤和分页功能,并将输入参数作为查询参数传递。例如
http://api.com/device-management/managed-devices
http://api.com/device-management/managed-devices?region=USA
http://api.com/device-management/managed-devices?region=USA&brand=XYZ
http://api.com/device-management/managed-devices?region=USA&brand=XYZ&sort=installation-date
7.不要在末尾使用/
作为URI路径中的最后一个字符,正斜杠(/)不会添加语义值,并可能导致混淆。最好完全放弃它们。
8.使用http状态码定义api执行结果
1xx:信息
通信传输协议级信息。
2xx:成功
表示客户端的请求已成功接受。
3xx:重定向
表示客户端必须执行一些其他操作才能完成其请求。
4xx:客户端错误
此类错误状态代码指向客户端。
5xx:服务器错误
服务器负责这些错误状态代码。
另外完整的更为详细的状态码此处不做赘述。一般简化版本的api会使用200,400,500,其中400代表客户端调用有误,将错误信息放入response:
{ "error": "username.or.password.error" }
9.api版本定义
当我们需要对现有的api接口升级的时候,因为该api接口已经投入使用,所以新添加的业务可能无法保证兼容原来的逻辑,这个时候就需要新的接口,而这个接口一般表示对原来的接口的升级(不同版本),那版本怎么定义呢?
URI版本控制(推荐)
http://api.com/v1
http://v1.api.com
使用自定义请求标头进行版本控制
Accept-version:v1
Accept-version:v2
使用Accept header 进行版本控制
Accept:application / vnd.v1 + json
Accept:application / vnd + json; version = 1.0
使REST API无状态有一些非常显着的优点:
那么无状态又要怎么实现呢?前面我们已经说了,服务端不应该再保存session会话,这个工作全部交由http请求去标识,而最常见的做法则是使用token。生成token可以考虑使用jwt,oauth。
rest api的约束设计,简单来说就是url地址中只包含名词表示资源,使用http动词表示动作进行操作资源。举个例子:左边是错误的设计,而右边是正确的
GET /blog/getArticles --> GET /blog/Articles 获取所有文章 GET /blog/addArticles --> POST /blog/Articles 添加一篇文章 GET /blog/editArticles --> PUT /blog/Articles 修改一篇文章 GET /rest/api/deleteArticles?id=1 --> DELETE /blog/Articles/1 删除一篇文章
评论已关闭。