浅谈RESTful风格下的API接口设计

前言

百度百科

RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义。 RESTFUL适用于移动互联网厂商作为业务使能接口的场景，实现第三方OTT调用移动网络资源的功能，动作类型为新增、变更、删除所调用资源。

理解

RESTful是一套通俗的约定和标准, 是协议通信的双方共同遵守的约定.
REST架构的核心便是REST : Representational State Transfer

1. Resources (资源)

URI是每个资源地址的独一无二的识别符
资源可以简单的理解成互联网上的信息, 在具体的服务端可以将其理解成对象, entity实体, 数据库表内的一行数据, 在REST风格中可以将其等同于信息的最小载体, 而URI则是与每一个具体的信息的地址所一一对应. 显示/操作这一资源需要通过对这一资源对应的URI进行处理来达到相应的目的

2. Representation(表现层)

在HTTP请求中, 请求头中的Accept/Content-Type等字段则表示了表现形式的要求
资源只代表信息的本体, 并不会表示信息的表现形式, 而信息的具体表现形式则为HTML/XML等. 通常所见的表现形式包括但不限于图片(jpg/png), 文本(txt/html/xml/json), 表格excel, 文档pdf等等.

3. State Transfer(状态转换)

在HTTP请求中, 随着信息的交换, 一定伴随着状态的转换
HTTP是一种无状态的协议, 在通信的过程中, 并不会携带具体的状态信息, 所有的状态信息都会保存在服务端, 如果需要操作具体的资源, 则需要更改资源的状态信息. 而这种转换是建立在"表现层"上面的, 就是所谓的"表现层状态转换".
HTTP的动作对应资源的操作形式. GET/POST/PUT/DELETE

一个奇怪的理解
资源 --> html(看的啥)
表现层 --> css(咋看)
状态装换 --> js(动画/状态改变)

疑问

1. 通过操作资源的表现形式来操作资源? 这句话怎么理解?
2. 表现层状态转化 为什么这么命名?

HTTP相关

符合REST设计风格的Web API称为RESTful API。它从以下三个方面资源进行定义：

• 直观简短的资源地址：URI，比如：http://example.com/resources
• 传输的资源：Web服务接受与返回的互联网媒体类型，比如：JSON，XML，YAML等
• 对资源的操作：Web服务在该资源上所支持的一系列请求方法（比如：POST，GET，PUT或DELETE）

一个表表示一下区别

URI	GET	PUT	POST	DELETE
http:xxx.com/resources	获得改资源组的详细信息	使用给定的一组资源替换当前整组资源	在本组资源中创建/追加一个新的资源	删除整组资源
http:xxx.com/resource/1	获得改资源为1的详细信息	替换/创建指定的资源。并将其追加到相应的资源组中	把指定的资源当做一个资源组，并在其下创建/追加一个新的元素，使其隶属于当前资源	删除为1的资源

HTTP方法的选用标准

要严格按照安全性和幂等性的要求来选用HTTP的方法

• 安全性: 不改变资源
• 幂等性: 多次执行的结果一样

\	GET	PUT	POST	DELETE	HEAD	PATCH
安全性	√	×	×	×	√	×
幂等性	√	√	×	√	√	×

URI规范/约定

1. 禁止大写
2. 如需用 - ,用 - , 不用 _
3. 编码格式要encode

decode encode
str ---------> unicode --------->str

4. URI表示资源集合使用复数形式, 否则使用单数形式
5. 每一个URI表示一个资源, 所以不能含有动词(除了http方法不能代表的动作)
6. 避免层级过深的URI, 否则会引起URI膨胀, 不宜维护

状态码

§200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
§201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
§202 Accepted - [*]：表示一个请求已经进入后台排队（异步任务）
§204 NO CONTENT - [DELETE]：用户删除数据成功。
§400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
§401 Unauthorized - [*]：表示用户没有权限（令牌、用户名、密码错误）。
§403 Forbidden - [*] 表示用户得到授权（与401错误相对），但是访问是被禁止的。
§404 NOT FOUND - [*]：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
§406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
§410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
§422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
§500 INTERNAL SERVER ERROR - [*]：服务器发生错误，用户将无法判断发出的请求是否成功。

cr:
HTTP方法的幂等性与安全性
理解RESTful架构 - 阮一峰的网络日志
表现层转换 - *
RESTful的一些注意事项 - 简书

江湖梦