RESTful restful api Representational State Transfer

通俗直白讲：REST是一种编写风格，一种API接口规范。它的风格就是将对象（如学生）的状态（如增删改查，API接口版本号等等）通过其他方式传递，API的接口地址突显出描述的对象。

--

==

REST/RESTful大概就是以下的实现步骤

1. 用URL/URI来表示Object 例如 http://www.example.com/order/111111 来表示一个订单

2.用标准的HTTP协议来完成逻辑操作，通常有以下几个对应 HTTP Get来获得一个订单的内容，HTTP Put来更新一个订单， HTTP Post来新增一个订单， HTTP Delete来删除一个订单。

3. 无状态，一般指的是服务器端不保留任何操作和事务的状态，也就不存在类似回滚的操作

--

具体风格样式可以参考以下

RESTful风格Api

1.RESTful api接口规范：

（1）协议

API与用户的通信协议，总是使用HTTPs协议，确保交互数据的传输安全。

（2）域名应该尽量将API部署在专用域名之下。

https://api.example.com

如果确定API很简单，不会有进一步扩展，可以考虑放在主域名下。

https://example.org/api/

（3）api版本控制

应该将API的版本号放入URL。

https://api.example.com/v{n}/

另一种做法是，将版本号放在HTTP头信息中，但不如放入URL方便和直观。Github采用这种做法。

采用多版本并存，增量发布的方式。

v{n} n代表版本号,分为整形和浮点型；

整形的版本号: 大功能版本发布形式；具有当前版本状态下的所有API接口 ,例如：v1,v2；

浮点型：为小版本号，只具备补充api的功能，其他api都默认调用对应大版本号的api 例如：v1.1 v2.2

（4）API 路径规则

路径又称"终点"（endpoint），表示API的具体网址。在RESTful架构中，每个网址代表一种资源（resource），所以

网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记

录的"集合"（collection），所以API中的名词也应该使用复数。

举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。

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

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

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

（5）HTTP请求方式

对于资源的具体操作类型，由HTTP动词表示。

常用的HTTP动词有下面四个（括号里是对应的SQL命令）。

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

POST（CREATE）：在服务器新建一个资源。

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

DELETE（DELETE）：从服务器删除资源。

下面是一些例子。

GET /product/ID/purchase ：列出某个指定商品的所有投资者

GET /product/ID/purchase/ID：获取某个指定商品的指定投资者信息

GET /product：列出所有商品

GET /product/ID：获取某个指定商品的信息

POST /product：新建一个商品

PUT /product/ID：更新某个指定商品的信息

DELETE /product/ID：删除某个商品

（6）过滤信息

如果记录数量很多，服务器不可能都将它们返回给用户。API应该提供参数，过滤返回结果。

下面是一些常见的参数。

?limit=10：指定返回记录的数量

?offset=10：指定返回记录的开始位置。

?page=2&per_page=100：指定第几页，以及每页的记录数。

?sortby=name&order=asc：指定返回结果按照哪个属性排序，以及排序顺序。

?producy_type=1：指定筛选条

（7）API 传入参数

参入参数分为4种类型：

（a）地址栏参数

restful 地址栏参数 /api/v1/product/122 122为产品编号，获取产品为122的信息

get方式的查询字串 见过滤信息小节

（b）请求body数据

cookie

request header

cookie和header 一般都是用于OAuth认证的2种途径

（c）返回数据

只要api接口成功接到请求，就不能返回200以外的HTTP状态。

为了保障前后端的数据交互的顺畅，建议规范数据的返回，并采用固定的数据格式封装。

接口返回模板：

{

status:0,

data:{}||[],

msg:’’
            }
                    status：接口的执行的状态

=0表示成功

<0 表示有异常=""

Data：接口的主数据，可以根据实际返回数组或JSON对象。

Msg：当status!=0 都应该有错误信息。

==

==

REST（英文：Representational State Transfer，简称REST）

representational state transfer
表述性状态转移;表现状态传输

representational
英 [ˌreprɪzenˈteɪʃnl] 入哎普神提手 。.美 [ˌrɛprɪzɛnˈteʃənəl, -zən-]
adj.
代表性的，具象派的

在目前主流的三种Web服务交互方案中，

REST相比于SOAP（Simple Object Access protocol，简单对象访问协议）

以及XML-RPC更加简单明了，

无论是对URL的处理

还是对Payload的编码，

REST都倾向于用更加简单轻量的方法设计和实现。

值得注意的是REST并没有一个明确的标准，

而更像是一种设计的风格。

三种Web服务交互方案：

REST（representational state transfer ，表述性状态转移）

SOAP（Simple Object Access protocol，简单对象访问协议）

XML-RPC

--

REST是一种风格样式。 没有统一标准。是一个概念。

REST用于 web 服务和动态 Web 应用程序的多层架构

可以实现可重用性、简单性、可扩展性和组件可响应性的清晰分离。

--

在 REST 样式的 Web 服务中，每个资源都有一个地址。、

资源指的是 如：应用程序对象、数据库记录、算法等等。

资源本身都是方法调用的目标，方法列表对所有资源都是一样的。

这些方法都是标准方法，包括 HTTP GET、POST、PUT、DELETE，还可能包括 HEAD 和 OPTIONS。

在 RPC 样式的架构中，关注点在于方法，而在 REST 样式的架构中，关注点在于资源。

==

这样的概念 解释还是太虚。

应该有具体的内容 例子。

举例来说，某个URI是/posts/show/1，其中show是动词，这个URI就设计错了，正确的写法应该是/posts/1，然后用GET方法表示show。

如果某些动作是HTTP动词表示不了的，你就应该把动作做成一种资源。比如网上汇款，从账户1向账户2汇款500元，错误的URI是：

　　POST /accounts/1/transfer/500/to/2

正确的写法是把动词transfer改成名词transaction，资源不能是动词，但是可以是一种服务：

　　POST /transaction HTTP/1.1
　　Host: 127.0.0.1
　　
　　from=1&to=2&amount=500.00

另一个设计误区，就是在URI中加入版本号：

　　http://www.example.com/app/1.0/foo

　　http://www.example.com/app/1.1/foo

　　http://www.example.com/app/2.0/foo

因为不同的版本，可以理解成同一种资源的不同表现形式，所以应该采用同一个URI。版本号可以在HTTP请求头信息的Accept字段中进行区分（参见Versioning REST Services）：

　　Accept: vnd.example-com.foo+json; version=1.0

　　Accept: vnd.example-com.foo+json; version=1.1

　　Accept: vnd.example-com.foo+json; version=2.0

==