一、什么是REST?
REST是 Representational State Transfer ,翻译过来是表现层状态转移的意思,是一组架构约束条件和原则,“表现层”指的是资源的“表现层”。
在REST架构风格中,对象被抽象为一种资源。资源的命名使用概念清晰的名词来定义。表现层状态是对资源数据在某个瞬间状态的快照,资源的某个瞬时状态被定义为一种表现(representation),这种描述性的状态包括资源数据的内容、表述格式(比如XML、JSON)等信息,一种资源可以对应多种表述。
REST或者可以简单理解为URL定位资源,用HTTP动词(GET,POST,DELETE,DETC)描述操作
。
REST原则:
<1>网络上的所有事物都被抽象为资源
<2> 每个资源都有一个唯一的资源标识符uri
<3> 同一个资源具有多种表现形式(xml,json等)
<4> 对资源的各种操作不会改变资源标识符
<5> 所有的操作都是无状态
的
无状态(Stateless)
所谓无状态的,即所有的资源,都可以通过URI定位,而且这个定位与其他资源无关,也不会因为其他资源的变化而改变。有状态和无状态的区别,举个简单的例子说明一下。如查询员工的工资,如果查询工资是需要登录系统,进入查询工资的页面,执行相关操作后,获取工资的多少,则这种情况是有状态的,因为查询工资的每一步操作都依赖于前一步操作,只要前置操作不成功,后续操作就无法执行;如果输入一个url即可得到指定员工的工资,则这种情况是无状态的,因为获取工资不依赖于其他资源或状态,且这种情况下,员工工资是一个资源,由一个url与之对应,可以通过HTTP中的GET方法得到资源,这是典型的RESTful风格。
REST 是面向资源的,这个概念非常重要,而资源是通过 URI 进行暴露
二、什么是RESTful?
基于REST构建的API就是Restful风格。
REST 指的是一组架构约束条件和原则,不是指标准;满足这些约束条件和原则的应用程序或设计就是 RESTful。
三、如何设计Restful风格的API
REST描述的是在网络中client和server的一种交互形式;REST本身不实用,实用的是如何设计 RESTful API(REST风格的网络接口)。
路径(Endpoint)
路径又称"终点"(endpoint),表示API的具体网址,每个网址代表一种资源(resource)。
(1) 资源作为网址,只能有名词,不能有动词,而且所用的名词往往与数据库的表名对应。
(2) API中的名词应该使用复数。无论子资源或者所有资源。
统一接口(Uniform Interface)
RESTful架构风格规定,数据的元操作,即CRUD(create, read, update和delete,即数据的增删查改)操作,分别对应于HTTP请求方法,这样就统一了数据操作的接口,仅通过HTTP方法,就可以完成对数据的所有增删查改工作。
请求方法的设计
GET(SELECT):获取资源(一项或多项)。
POST(CREATE):新建一个资源。
PUT(UPDATE):更新资源(全更新,需提供完整资源数据)。
PATCH(UPDATE):更新资源(部分更新)。
DELETE(DELETE):从服务器删除资源。
HEAD:获取资源的元数据。
OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。
过滤信息(Filtering)
如果记录数量很多,服务器不可能都将它们返回给用户。API应该提供参数,过滤返回结果。
下面是一些常见的参数。
?limit=10:指定返回记录的数量
?offset=10:指定返回记录的开始位置。
?page=2&per_page=100:指定第几页,以及每页的记录数。
?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序。
?animal_type_id=1:指定筛选条件
状态代码设计
http返回包最重要是状态吗,请求只有几种,但返回结果有无数种可能,HTTP 状态码就是一个三位数,分成五个类别。
- 1xx:相关信息
- 2xx:操作成功
- 3xx:重定向
- 4xx:客户端错误
- 5xx:服务器错误
这五大类总共包含100多种状态码,覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的(或者约定的)解释,客户端只需查看状态码,就可以判断出发生了什么情况,所以服务器应该返回尽可能精确的状态码。
一下列举一些常用的状态码
状态码 | 描述 | 含义 |
---|---|---|
200 | OK - [GET] | 服务器成功返回用户请求的数据 |
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 - [*] | 服务器发生错误,用户将无法判断发出的请求是否成功。 |
返回结果
针对不同操作,服务器向用户返回的结果应该符合以下规范。
GET /collection:返回资源对象的列表(数组)
GET /collection/resource:返回单个资源对象
POST /collection:返回新生成的资源对象
PUT /collection/resource:返回完整的资源对象
PATCH /collection/resource:返回完整的资源对象
DELETE /collection/resource:返回一个空文档
错误处理(Error handling)
如果状态码是4xx,服务器就应该向用户返回出错信息。一般来说,返回的信息中将error作为键名,出错信息作为键值即可。
其他
服务器返回的数据格式,应该尽量使用JSON,避免使用XML。
参考:
https://blog.csdn.net/qq_21383435/article/details/80032375