REST概述

RESTful 是目前最流行的 API 设计规范，用于 Web 数据接口的设计。
REST即Representational state transfer（表现层状态转化），首次出现在Roy Thomas Fielding（HTTP协议1.0、1.1主要设计者，第一任Apache基金会主席…）的博士论文中，感兴趣的朋友，可参见https://www.ics.uci.edu/~fielding/pubs/dissertation/fielding_dissertation.pdf 76页第五章“Representational State Transfer (REST)”，或者查看中译版（李锟、廖志刚等）。
REST-中译版.pdf

REST目标

引用下Roy Fielding的原话：

This dissertation explores a junction on the frontiers of two research disciplines in computer science: software and networking. Software research has long been concerned with the categorization of software designs and the development of design methodologies, but has rarely been able to objectively evaluate the impact of various design choices on system behavior. Networking research, in contrast, is focused on the details of generic communication behavior between systems and improving the performance of particular communication techniques, often ignoring the fact that changing the interaction style of an application can have more impact on performance than the communication protocols used for that interaction. My work is motivated by the desire to understand and evaluate the architectural design of network-based application software through principled use of architectural constraints, thereby obtaining the functional, performance, and social properties desired of an architecture.

翻译过来，大意：本文主要目标是研究软件与网络的交叉点。软件研究很少涉及评估不同设计选择对系统行为影响，而是将关注点放在软件设计分类及演变上；而相反，网络研究很少涉及改变应用程序的互动风格相较改变互动协议对整体表现的影响，而是更多关注系统之间通信行为的细节、如何改进特定通信机制的表现。因此这篇文章的目的—理解和评估以网络为基础的应用软件的架构设计，得到一个功能、性能、通信方面更优的架构。

REST约束

客户-服务器（Client-Server）：服务器、客户端隔离区分对待。
无状态（Stateless）：来自客户的每一个请求，必须包含服务器处理该请求所需的所有信息，即服务器端无请求状态存储。
可缓存（Cachable）：服务器无论是显示还是隐示，但必须让客户知道请求是否可以被缓存。
统一接口（Uniform Interface）：客户和服务器之间通信的方法必须是统一化的。统一接口涵盖4条子约束：

1. 资源Identifier：每个资源定义一个唯一标识，即通过这个唯一标识有且仅能找到该资源；
2. 消息的自描述：client传递的消息需要能够提供足够信息告知server其自身该如何被处理。例如该消息所使用的MIME类型是html、xml、json还是其它，是否可以被缓存等。
3. 资源的自描述：server端返回给client的消息能够足够描述自身即相关操作信息。如对资源的增、删等操作进行描述。
4. 超媒体作为应用状态的引擎（HATEOAS）：客户端通过服务器提供的动作来进行状态转换。

分层系统（Layered System）：服务器和客户之间的通信标准化，即：允许服务器和客户之间的中间层可以代替服务器对客户的请求进行回应，而且这些对客户来说不需要特别支持。
支持按需代码（Code-On-Demand）：可选约束，服务器可以提供一些代码或者脚本并在客户的运行环境中执行。

REST风格优势

通常使用的分布式应用架构风格有三种：

• 分布式对象（Distributed Objects，简称DO）：架构实例如RMI、EJB/DCOM、.NET Remoting等；
• 远程过程调用（Remote Procedure Call，简称RPC）：架构实例如SOAP、XML-RPC、Flash AMF等；
• 表述性状态转移（Representational State Transfer，简称REST）：架构实例如HTTP、WebDAV等；

DO和RPC这两种架构风格在传统企业应用中非常普遍，REST则是Web应用的架构风格。
REST相较于DO、RPC，优势体现在：

1. REST支持抽象的目标是资源，DO支持抽象的目标是对象，RPC支持抽象的目标是过程。REST中的资源，不需要依赖开发平台或编程语言；由于不同的编程语言对象的定义有很大差别，DO风格的架构通常与某种编程语言绑定的，若跨语言交互，实现起来也会非常复杂；REST风格以名词为核心，而RPC风格则以动词为核心。
2. DO、RPC中无统一接口的概念。不同的API，接口设计风格可以完全不同。
3. REST使用超文本，响应的内容中只包含消息本身，交互力度更大，效率相较DO更高。
4. REST支持数据流和管道，而DO、RPC不支持。
5. REST client与server端松耦合，RPC与DO风格通常会带来客户端与服务器端的紧耦合。

   REST剖析

   URI

   在REST定义中，其实省略了URI（Uniform Resource Identifier）这个对象，这里对URI、URL、URN几个常用词做一个名词解释：

• URI（Uniform Resource Identifier）：即统一资源标识，是统一紧凑的字符串表示物力资源或抽象；
• URL（Uniform Resource Loader）：即我们常听到的统一资源定位符，是URI的子集，是URI两种形式中的一种，如https://www.baidu.com是URL，其侧重点在于“位置”定位；

• URN（Uniform Resource Name）：即统一资源名词，是URI的子集，是URI另一种形式，如urn:names:xml:1.0，“位置”无关，通常说的Magnet URI scheme（磁力链接）及时URN的一种实现；

  Representation

  表现层，通常把网络资源最终如何展现描述，称为“Representation”，比如，发送请求，请求接口，期望发送的信息体是“json”格式，期望接收到的结果也是“json”格式，那么对于这个请求的“表述”，可以定义header：

• Content-Type: Application/json

• Accept: Application/json

  State Transfer

  REST约束中约定了无状态特性，这个无状态针对的是server端，client端需要维护client用户状态变化。通过HTTP协议，设置不同的请求“方法”，告知server端，server端接收到处理“资源”请求，并给出响应。URI是资源标识，在请求前后不变，而变动的是“资源”的“表现层”内容，client最终识别到“资源”“表现层”变化，因此称为“Representational State Transfer”。如client 端发送

  GET /servers
  Content-Type: application/json
  Accept: application/json

  请求，服务器端根据“资源”（/servers），返回结果

  {json data}
  Content-Type: text/html;charset=utf-8
  Response code: 200

  RESTful API定义

  符合REST规范设计的接口，称为RESTful API。

URI定义

版本(Version)

描述的是资源或接口的迭代阶段，通常version可以有3中定义方式：

• 版本定义在response的header中，如：

  Accept: Application/json; version=1.1;

• 版本定义在response数据中，如返回data为JSON格式：

  {
    version: 1.1,
    resource: {...}
  }

• 版本定义在URI中，如：

  GET /v1.1/resources

  从笔者工作经历来讲，通常用到第3种，其理由：

1. 用于前后端分离，提供JSON数据，header和data中不太好处理或区分；
2. 调用接口时，已明确使用版本；
3. version版本并非跟单个资源相关，而是跟单个独立项目相关；

   资源(Resource)

   通常，我们理解的Resource是指操作对象的数字化抽象，以虚拟机为例，其属性构成部分包括：

• 基础描述信息：ID、name、description、metadata等；
• 硬件组成信息：disks、nics、cpu、内存等；
• 管理信息：boot image、managed hypervisor等；
• 状态信息：task status、status等；

当然，对于一个虚拟机这样的资源，也可以进行：

• 创建、删除、重新配置、查询等操作；
• 迁移、快照、开关机、重启、挂起、唤醒、休眠等操作；

在URI定义时，实际优先根据需求进行操作对象“建模”，如上面的server，定义清楚Resource的属性构成及操作方法构成，之后再配合操作Method，定义Resource的各种操作API。通常情况下，建议在URI定义时使用复数定义resource，如”/servers”（并非说一定不能使用单数）。

过滤(filter)

严格来说，filters不属于URI定义部分，通常用于查询时使用，一般用途为：

1. 分页分段查询：如”/servers?limit=10&maker=123356”；
2. 根据资源属性过滤查询：如”/servers?name=test”；
3. 过滤返回data显示字段：如”/servers?display_item=id,name,nics,disks”；
4. 排序查询：如”/servers?field=created_at&order=desc”

其定义格式为：

?key1=values1&key2=value2

filter在定义时，需要注意：

1. 根据url长度限制（不得超过255个字节），因此不要在filter总加入过长的过滤项；

2. 对filter进行encode，尤其是包含中文、{}、[]等特殊符号时；

   URI定义规则枚举

   罗列若干URI定义规则建议：

3. URI字符全小写：定义URI时，尽量不用大写字母，如”/servers”；

4. URI使用”/“区分层级：定义URI时，通常约定从左到右范围递减，如”GET /servers/123456”表示取servers中id为123456项，因此尽量不要以”/“作为URI结尾；
5. 使用”-“而非”“作为单词连接：在浏览器经常在 URI 下加下划线，以表示可点击的视觉提示，”“容易被忽略；
6. 尽量不要在URI定义中体现”.json、.html等”这样的后缀；
7. 定义URI时使用名词且尽量使用复数；

   操作方法(Method)

   HTTP操作方法

   常用的HTTP方法为：GET、POST、PUT、DELETE用以完成CURD操作，

• GET：通常用于获取查询列表或单个资源信息，如 ```http GET /v1/servers HTTP/1.1 Accept: application/json Content-Type: application/json

Response: data: [{
“name”: “host1”, “id”: “123456” }] status: 200

- **POST**：用于创建新资源或者触发动作，如
```http
POST /v1/servers HTTP/1.1
data: 
{
    "name": "host1",
    "flavor": "xxxx",
    "image": "xxxx",
    "nics": [{"net-id": "xxx"}]
}
Accept: application/json
Content-Type: application/json
Response:
data:
[{   
    "name": "host1",
    "id": "123456",
    "flavor": "xxxx",
    "image": "xxxx",
    "nics": [{"net-id": "xxx"}]
}]
status: 201

• PUT：用于更新资源属性，如 ```http PUT /v1/servers/123456 HTTP/1.1 data: { “name”: “host2” } Accept: application/json Content-Type: application/json

Response: data: [{
“name”: “host2”, “id”: “123456”, “flavor”: “xxxx”, “image”: “xxxx”, “nics”: [{“net-id”: “xxx”}] }] status: 200

- **DELETE**：用于删除资源，如
```http
DELETE /v1/servers/123456 HTTP/1.1
Accept: application/json
Content-Type: application/json
Response:
status: 202

除开上面的CURD操作对应的方法，还有OPTION、HEAD等不常用方法，
OPTION：在跨域或使用代理时，通常会用到OPTION方法，OPTION请求在于判定请求资源的选项或需求，或者服务器的能力；
HEAD：用来获取请求实体的元信息而不需要传输实体主体（entity-body）。此方法经常被用来测试超文本链接的有效性，可访问性，和最近的改变，例如获取虚拟机镜像信息，实体是镜像文件，通常调用HEAD方法获取镜像属性信息，通过GET方法获取镜像文件自身；
关于http方法详细定义，参看rfc文档。

安全性与幂等性

名词解释>
安全性：指调用http请求方法，执行结束后不会导致资源状态变化，详见Hypertext Transfer Protocol — HTTP/1.1-9.1.1；
幂等性：多次调用http请求方法，执行结果对资源改变等价，详见Hypertext Transfer Protocol — HTTP/1.1-9.1.2；
根据上面的定义，http方法，不能全部都无法确保多次请求得到的结果完全一致，http各常见方法安全性、幂等性见下表：

表现层定义

Header

HEADER是对RESTful API请求的描述，分为Request HEADER（client发送到server端，消息描述）和Response HEADER（server端返回消息描述），常见 Header Field Definitions。
Request相关HEADER（表格信息源自：HTTP Header 详解）

Response相关HEADER（表格信息源自：HTTP Header 详解）

Response Code

对于Response Code，通常指代HTTP Response code（详见 Status Code Definitions），有时也代指在返回data中的code，以http code为例，枚举（表格信息源自：HTTP状态码对照表）：

HyperMedia API

名词解释[HyperMedia](https://en.wikipedia.org/wiki/Hypermedia)：超媒体是一个非线性介质的信息包括图形、音频、视频、文本和超链接。源于REST约束属性“超媒体作为应用状态的引擎HATEOAS”，在定义RESTful API时，通常在返回中加入HyperMedia链接。
如，对于JSON返回数据：
Request为：

GET /v2.1/e5ab2182bb984f3bb4773d4a83672549/servers/detail HTTP/1.1
Host: 192.168.10.111
Accept: application/json
Content-Type: application/json

Response为：

HTTP/1.1 200 OK
Content-Type: application/json
{"servers": [{
    "status": "ACTIVE",
    "links": [{
        "href": "http://192.168.10.111:8774/v2.1/e5ab2182bb984f3bb4773d4a83672549/servers/95f684d4-0802-484e-b852-7ded35a8eeb5",
        "rel": "self"
    }, {
        "href": "http://192.168.10.111:8774/e5ab2182bb984f3bb4773d4a83672549/servers/95f684d4-0802-484e-b852-7ded35a8eeb5",
        "rel": "bookmark"
    }],
    "image": {
        "id": "be4e8e37-226f-4784-b19d-a439400edca0",
        "links": [{
            "href": "http://192.168.10.201:8774/e5ab2182bb984f3bb4773d4a83672549/images/be4e8e37-226f-4784-b19d-a439400edca0",
            "rel": "bookmark"
        }]
    },
    "flavor": {
        "id": "ed218eec-1e00-4ea9-93e7-f6e4e7c0ba93",
        "links": [{
            "href": "http://192.168.10.201:8774/e5ab2182bb984f3bb4773d4a83672549/flavors/ed218eec-1e00-4ea9-93e7-f6e4e7c0ba93",
            "rel": "bookmark"
        }]
    },
    "id": "95f684d4-0802-484e-b852-7ded35a8eeb5",
    ......
}]}

关于登陆验证

备注：此处单讨论说明登陆验证，是因为登陆验证违背了REST 无状态约束，因此对于登陆验证做一个专门的说明，限于篇幅，后续文档中详细介绍登陆及登陆实现！

什么是登陆验证

登陆验证要求

登陆验证源于用户使用WEB应用，记录用户身份状态的需求，其特点是：

1. 用户使用用户相关信息（如常见的用户名、密码）验证后，对应服务器、client端可记录用户信息；
2. 用户登陆后，不需要在交互时进行不断对于身份的告知，除非用户登陆状态过期或用户自动退出登陆；

3. 用户登陆状态一般情况下是有过期时间的，通常定义为一段时间没有进行交互操作（如1小时），则任务登陆状态过期，server、client端自动移除用户登陆状态；

   常见登陆验证方式

   通常在web应用中，可见2种登陆验证方式：

4. server端提供自维护登陆状态：即访问的server端记录并维护用户的登陆状态信息；

5. 第三方提供维护登陆状态：即由第三方server端记录并维护用户登陆状态信息，如常见的qq、微信、微博账号登陆，当然这种方式存在着“跨域问题”[后续文档专门讨论分析跨域问题]；

   验证实现若干方案

   
   图片源于：https://auth0.com/blog/cookies-vs-tokens-definitive-guide/

   cookies方式

   如上图，cookies方式，

• 在登陆时，在server端创建session，记录用户登陆状态及相关信息；
• 返回client后，client将session id存放于cookies中（浏览器可自动记录并存储）；

• 当登陆后发送的后续请求，client在request header中携带cookies中的session id信息，server端接收到后，验证session id是否合法，若合法则进行相关处理并给出响应；

  token方式

  token方式，

• 在登陆时，在server端创建session，记录用户登陆状态及相关信息；

• 返回client后，client需要通过脚本控制存放token信息；
• 当登陆后发送的后续请求，client在request header或body中携带cookies中的session id信息，server端接收到后，验证session id是否合法，若合法则进行相关处理并给出响应；