Representational State Transfer

含状态传输(Representational State Transfer,简称REST)是Roy Thomas Fielding博士在2000年他的博士论文中提出来的一种网络软件架构风格,目的是便于不同软件/程序在网络(例如互联网)中互相传递信息。

REST 是根基于超文本传输协议(HTTP)之上而确定的一组约束和属性,是一种设计提供万维网络服务的软件构建风格。匹配或兼容于这种架构风格(简称为 REST 或 RESTful)的网络服务,允许客户端发出以统一资源标识符访问和操作网络资源的请求,而与预先定义好的无状态操作集一致化。因此 REST 提供了在互联网络的计算系统之间,彼此资源可交互使用的协作性质(interoperability)。

目前在三种主流的Web服务实现方案中,因为REST模式与复杂的SOAP和XML-RPC相比更加简洁,越来越多的web服务开始采用REST风格设计和实现。例如,Amazon.com提供接近REST风格的Web服务运行图书查询;雅虎提供的Web服务也是REST风格的。

1. What Is REST?

https://www.restapitutorial.com/lessons/whatisrest.html REST架构风格描述了6个约束用于构建 RESTful 风格的应用。

1.1. Uniform Interface

统一接口约束定义了客户机和服务器之间的接口。它简化和解耦了体系结构,使每个部分能够独立发展。统一接口的四个指导原则是:

1.2. Stateless

无状态

1.3. Cacheable

在万维网上,客户机可以缓存响应。因此,响应必须隐式或显式地将自己定义为可缓存或不可缓存,以防止客户机在响应进一步请求时重用陈旧或不恰当的数据。管理良好的缓存部分或完全消除了一些客户机-服务器交互,进一步提高了可伸缩性和性能。

1.4. Client-Server

统一的接口将客户机和服务器分隔开来。这种关注点分离意味着,例如,客户机不关心数据存储,数据存储仍然是每个服务器内部的,因此客户机代码的可移植性得到了改进。服务器不关心用户界面或用户状态,因此服务器可以更简单和更可伸缩。只要界面不改变,服务器和客户端也可以被独立地替换和开发。

1.5. Layered System

客户端通常无法分辨它是直接连接到终端服务器,还是一路连接到中介。中介服务器可以通过启用负载平衡和提供共享缓存来提高系统的可伸缩性。层还可以执行安全策略。

1.6. Code on Demand (optional)

服务器可以通过传输可执行代码临时扩展或定制客户机的功能。

2. REST API Quick Tips

https://www.restapitutorial.com/lessons/restquicktips.html 如何判断一个系统在技术上是否 RESTful (根据前面提到的六个约束条件),这有一些推荐的判断标准:这几个快速提示将帮助我们设计出更好、更有用的 RESTful 服务。

2.1. Use HTTP Verbs

API使用者能够发送GET、POST、PUT和DELETE动词,这大大提高了给定请求的清晰度。

GET

PUT

DELETE

POST

2.2. Provide Sensible Resource Names

一个合理的资源名(只是URL路径,比如/customers/12345/orders)可以提高给定请求的清晰度。

适当的资源名称为服务请求提供上下文,增加了API的可理解性。通过URI名称以层次结构的方式查看资源,为使用者提供一个友好的、易于理解的资源层次结构,以便在应用程序中使用这些资源。

URL path (resource name) 设计原则:

2.3. HTTP Response Codes to Indicate Status

响应状态码是HTTP规范的一部分。有相当多的方法可以解决最常见的情况。为了让RESTful服务支持HTTP规范,我们的Web api应该返回相关的HTTP状态代码。例如,当资源成功创建(例如从POST请求创建)时,API应该返回HTTP状态码201。这里有一个有效的HTTP状态代码列表,其中列出了每一个的详细描述。更详细的Status Code: https://www.restapitutorial.com/httpstatuscodes.html

200 OK

201 CREATED

204 NO CONTENT

400 BAD REQUEST

401 UNAUTHORIZED

403 FORBIDDEN

404 NOT FOUND

405 METHOD NOT ALLOWED

409 CONFLICT

500 INTERNAL SERVER ERROR

2.4. Create Fine-Grained Resources

开始时,最好创建模仿系统的底层应用程序域或数据库体系结构的api来创建细粒度的资源。合并比拆分要容易。

稍后从单个资源创建更大的资源要比从更大的聚合创建细粒度或单个资源要容易得多。让您自己轻松点,开始使用小的、容易定义的资源,在这些资源上提供CRUD功能。您可以稍后创建那些面向用例的、减少交谈的资源。

2.5. Consider Connectedness

REST的原则之一是连接——通过超媒体链接(搜索HATEOAS)。虽然没有这些服务仍然有用,但是当响应中返回链接时,api变得更加自描述和可发现。至少,“self”链接引用可以告诉客户机数据是如何被检索的。另外,利用HTTP Location头包含一个通过POST(或PUT)创建资源的链接。对于响应中返回的支持分页的集合,“first”、“last”、“next”和“prev”链接至少是非常有用的。

3. Richardson Maturity Model

https://martinfowler.com/articles/richardsonMaturityModel.html RESTful API 成熟度模型

maturity-model.png

4. HTTP Methods for RESTful Services

https://www.restapitutorial.com/lessons/httpmethods.html

HTTP动词构成了“统一接口”约束的主要部分,并为我们提供了与基于名词的资源对应的操作。主要的或最常用的HTTP动词(或正确称为方法)是POST、GET、PUT、PATCH和DELETE。它们分别对应于创建、读取、更新和删除(或CRUD)操作。

下表总结了 典型 HTTP 方法与资源 URI 相结合的推荐返回值

HTTP 请求方法在RESTful Web 服务中的典型应用

HTTP Verb

CRUD

Entire Collection (e.g. /customers)

Specific Item (e.g. /customers/{id})

POST

Create

201 (Created), 'Location' header with link to /customers/{id} containing new ID.

404 (Not Found), 409 (Conflict) if resource already exists..

GET

Read

200 (OK), list of customers. Use pagination, sorting and filtering to navigate big lists.

200 (OK), single customer. 404 (Not Found), if ID not found or invalid.

PUT

Update/Replace

405 (Method Not Allowed), unless you want to update/replace every resource in the entire collection.

200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.

PATCH

Update/Modify

405 (Method Not Allowed), unless you want to modify the collection itself.

200 (OK) or 204 (No Content). 404 (Not Found), if ID not found or invalid.

DELETE

Delete

405 (Method Not Allowed), unless you want to delete the whole collection—not often desirable.

200 (OK). 404 (Not Found), if ID not found or invalid.

5. Idempotence

幂等性是一个很时髦的词,经常让人着迷。

从 RESTful 服务的角度来看,对于幂等的操作(或服务调用),客户端可以重复地进行相同的调用,同时产生相同的结果。换句话说,发出多个相同的请求与发出单个请求的效果相同。注意,虽然幂等操作在服务器上产生了相同的结果(没有副作用),但是响应本身可能不是相同的(例如,请求之间资源的状态可能会改变)。

将PUT和DELETE方法定义为幂等。然而,有一个关于删除的警告。如果删除成功,通常会返回一个200 (OK)或204(无内容),但在后续调用中通常会返回一个404(未找到),除非服务配置为“标记”资源以便删除,而不实际删除它们。然而,当服务实际删除资源时,下一个调用将不会找到删除资源并返回404。但是,每次删除调用之后服务器上的状态都是相同的,但是响应是不同的。

GET、HEAD、选项和跟踪方法被定义为安全的,这意味着它们仅用于检索数据。这也使它们具有幂等性,因为多个相同的请求的行为是相同的。

6. Frameworks

6.1. Spring RESTful(since v3.0)

6.2. Node.js

7.1. GraphQL

8. Reference


CategoryDesign

MainWiki: Representational_State_Transfer (last edited 2018-09-10 19:07:12 by twotwo)