RESTful风格学习

RESTful

定义

REST（representational state transfer，表述状态转换）作为一种软件架构风格、设计风格，而非标准，只提供一组设计原则与约束条件。主要作用于客户端和服务器交互的软件，使其更加简洁、更有层次和更易于实现缓存等机制。

特征

以资源为基础

可以是文本、图片、音频资源，或XML、HTML和JSON等格式的实体。

统一接口

包括获取、创建、修改和删除，对应HTTP协议提供的GET、POST、PUT、DELETE方法。
使用RESTful风格的接口只能定位资源，但无法知晓其具体进行的操作，只能从其HTTP请求方法类型上判断具体动作。

URI（universal resource identifier，统一资源标志符）指向资源

RESTful面向资源，每种资源可能有多个URI对应，但每个URI只能指向单个资源。

无状态

服务器不保留客户端信息，会话完全保留在客户端中。每一次客户端发送请求必须包含所有必要的状态信息，服务器端根据这些信息处理请求。

约束条件/原则

Client-Server Architecture：将用户界面及数据存储问题分开，简化服务器组件

客户端服务端解耦，提高跨平台可移植性，提高可扩展性

Statelessness：客户端每个请求包含所有必须信息，不能利用服务器存储的上下文，会话完全保存在客户端

易于扩展，无会话依赖，易缓存，提升程序性能

Cacheability：服务器端的响应需要被隐式或显式地标记出是否可以缓存，客户端获得在等效请求时重用可缓存的响应的权利

减少带宽，减少延迟，减少服务器负载，隐藏网络状态

Layered System：允许架构分层组成，使得每个组件只能与相邻层交互，将系统知识限制在单个层

降低系统复杂性，促进底层独立性，易于实施负载均衡，业务逻辑与安全策略解耦

Uniform Interface

resource identification in requests：通过请求识别资源

resource manipulation through representations：通过资源的表示（URI等）对资源进行操作

self-descriptive messages：消息应该包含如何处理自身

hypermedia as the engine of applicaton state：服务器返回的资源链接使用户获取所有资源，无须额外编码

简化整体系统架构，调高交互可见性

Code on Demand（optional）：允许通过发送特殊形式或脚本形式的代码对客户端进行功能扩展

提高可扩展性

RESTful API设计规范

URL设计规范

URI = scheme "://" host ":" port "/" path [ "?" query ][ "#" fragment ]
scheme底层使用协议，如http、https、ftp
host服务器IP地址或域名
port端口，http默认端口为80
path访问资源的路径，即各种web框架中定义的route路由
query查询字符串，发送给服务器的参数
fragment锚点，定位到页面的资源

针对API设计时，URL的path是需要进行规范的，RESTful API的path组成如：

/{version}/{resources}/{resource_id}
级别过大时可细分子资源：
/{version}/{resources}/{resource_id}/{subresources}/{subresource_id}
当增删改查无法满足业务要求，可以使用在结尾加操作action：
/{version}/{resources}/{resource_id}/action

具体规范：

a. 全部小写英文描述
b. URL层级不要过深，越靠前的层级应相对更稳定
c. 结尾不包含"/"
d. URL中不出现动词，用请求表示动作
e. 资源表示用复数形式
f.不使用文件拓展名

HTTP动词

RESTful风格的API要求URL上操作都以名词请求方式出现，与非RESTful风格的API不同，其会有操作的动词来表示API的操作，如query add update delete等

GET /collection：从服务器查询资源的列表（数组）
GET /collection/resource：从服务器查询单个资源
POST /collection：在服务器创建新的资源
PUT /collection/resource：更新服务器资源
DELETE /collection/resource：从服务器删除资源

安全性与幂等性

安全性：方法不会修改资源状态，即读操作为安全，写操作为非安全

幂等性：操作一次与操作多次的最终效果相同，客户端重复调用也只返回一个结果

上述四个HTTP请求方法的安全性与幂等性如下（知乎bigsai作图)

状态码和返回数据

服务器响应时包含状态码和返回数据两部分，告知客户端操作结果。不同团队的返回实体类不同，但都返回JSON格式数据给客户端。

状态码

1xx：相关信息

2xx：操作成功

200OK - [GET]：服务器成功放回用户请求的数据，该操作使幂等的
201CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功
202Accepted - [*]：表示一个请求已经进入后台排队（异步）
204NO CONTENT - [DELETE]：用户删除数据成功

3xx：重定向

4xx：客户端错误

400INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的
401Unauthorized - [*]：表示用户没有权限
403Forbidden - [*]：表示用户得到授权（与401错误相对），但是访问是被禁止的
404NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的
406Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）
410Gone -[GET]：用户请求的资源被永久删除，且不会再得到的
422Unprocesable entity - [POST/PUT/PATCH]：当创建一个对象时，发生一个验证错误

5xx：服务器错误

500INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功

资源链接

根据RESTful风格中的hypermedia as the engine of application state原则，要求在表述格式中加入链接来引导客户端，一个连接跳转至一个对应页面，达成将所有资源链接起来的效果（连通性）。
eg.

状态的转移

RESTful风格中要求遵循无状态的规则，是指服务端不应保有客户端状态，相应的客户端应该具有状态及状态的转移。即客户端负责维护应用状态，服务端维护资源状态。
”会话状态“只能作为应用状态被客户端进行跟踪，客户端应用状态在服务端提供的超媒体指引下发生变迁，服务端通过超媒体告诉客户端当前状态下有哪些后续状态可以转移进入。