RESTful设计风格

一、RESTfull设计风格
1、什么是RESTful？

1）REST：即Representational State Transfer的缩写。维基百科称其为“具象状态传输”，国内大部分人理解为“表现层状态转化”。

2）具象的：就是指表现层，要表现的对象也就是“资源”，什么是资源呢？网站就是资源共享的东西，客户端（浏览器）访问web服务器，所获取的就叫资源。比如html，txt，json，图片，视频等等。

3）表现：比如，文本可以用txt格式表现，也可以用HTML格式、XML格式、JSON格式表现，甚至可以采用二进制格式；图片可以用JPG格式表现，也可以用PNG格式表现。

浏览器通过URL确定一个资源，但是如何确定它的具体表现形式呢？应该在HTTP请求的头信息中用Accept和Content-Type字段指定，这两个字段才是对"表现层"的描述。

4）状态转换： 就是客户端和服务器互动的一个过程，在这个过程中, 势必涉及到数据和状态的变化, 这种变化叫做状态转换。

互联网通信协议HTTP协议，客户端访问必然使用HTTP协议，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。

总结：

REST与技术无关，代表的是一种软件架构风格

REST从资源的角度审视审视整个网络，它将分布在网络中某个节点的资源通过URL进行标识

所有的数据，无论是通过网络获取的还是操作（增删改查）的数据，都是资源。将一切数据视为资源是REST区别于其他架构风格的最本质的属性。

每一个URL代表一种资源

客户端和服务器之间，传递这种资源的某种表现层；

客户端通过HTTP动词对服务器端资源进行操作，实现“表现层状态转化”（GET,POST,PUT,DELETE）

2、RESTfull设计规范

1.域名

1）子域名方式

https://api.example.com 尽量将API部署在专用域名（会存在跨域问题）

https://www.example.com

2）url方式

https://example.org

https://example.org/api/ API很简单

2.版本

将API的版本号放入URL中。

https://api.example.com/v1/

https://api.example.com/v2/

https://api.example.com/v3/

3.路径

路径又称“终点”，表示API的具体网址，每个网址代表一种资源

1） 资源作为网址，只能有名词，不能有动词，而且所用的名词往往与数据库的表名对应。

2）API中的名词应该使用复数。无论子资源或者所有资源。

/getProducts　　　　不符合REST风格

/Orders 　　　　　　 符合REST风格

获取单个产品：http://127.0.0.1:8080/AppName/products/1

获取所有产品：http://127.0.0.1:8080/AppName/products

4.方式

GET ：从服务器取出资源（一项或多项）

POST ：在服务器新建一个资源

PUT ：在服务器更新资源（客户端提供改变的完整资源）

PATCH ：在服务器更新资源（客户端提供改变的属性）

DELETE ：从服务器删除资源

5.过滤

通过在url上传参的形式传递搜索条件

https://api.example.com/v1/zoos?limit=10：指定返回记录的数量

https://api.example.com/v1/zoos?offset=10：指定返回记录的开始位置

https://api.example.com/v1/zoos?page=2&per_page=100：指定第几页，以及每页的记录数

https://api.example.com/v1/zoos?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序

https://api.example.com/v1/zoos?animal_type_id=1：指定筛选条件

6.状态码

状态码

7.异常处理

如果状态码是4xx，服务器就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值即可。

{ error: “Invalid API key” }

8.返回结果

针对不同操作，服务器向用户返回的结果应该符合以下规范。

GET /collection：返回资源对象的列表（数组）

GET /collection/resource：返回单个资源对象

POST /collection：返回新生成的资源对象

PUT /collection/resource：返回完整的资源对象

PATCH /collection/resource：返回完整的资源对象

DELETE /collection/resource：返回一个空文档

9.超媒体（Hypermedia API）

RESTful API最好做到Hypermedia（即返回结果中提供链接，连向其他API方法），使得用户不查文档，也知道下一步应该做什么。

比如，Github的API就是这种设计，访问api.github.com会得到一个所有可用API的网址列表。

restful是一种软件设计风格，并不是标准，他只是提供了一组设计原则和约束条件
1.restful提倡面向资源编程，url接口尽量要使用名词，不要使用动词
2.在url中可以体现版本号
3.可以根据http不同的method，进行不同的资源操作
4.有返回值，而且格式为统一的json格式