Restful API 的接口规范

简介

REST 是 Representational State Transfer 三个单词的缩写，由Roy Fielding于2000年论文中提出的一种web软件结构风格，注意它仅仅只是代表着一种风格，并不代表着约束、标准。基于 REST 构建的API就是 Restful 风格。 如果一个架构符合 REST 的约束条件和原则，就称它为 Restful 架构。REST 本身并没有创造新的技术、组件或服务，而隐藏在RESTful背后的理念就是使用Web的现有特征和能力， 更好地使用现有Web标准中的一些准则和约束。虽然 REST 本身受 Web技术的影响很深， 但是理论上 REST 架构风格并不是绑定在 HTTP 上，只不过目前 HTTP 是唯一与 REST 相关的实例。

区别

举个例子说明 REST 设计

非 REST 设计，通常会这么写：

• 增：http://xxx.com:8080/posts/addAtricle
• 删：http://xxx.com:8080/posts/deleteAtricle
• 改：http://xxx.com:8080/posts/updateAtricle
• 查：http://xxx.com:8080/posts/getAtricle

REST 架构下可以这样写：

• 增：POST http://xxx.com:8080/posts/atricle
• 删：DELETE http://xxx.com:8080/posts/atricle
• 改：PUT ：http://xxx.com:8080/posts/atricle
• 查：GET http://xxx.com:8080/posts/atricle

总结：非 REST 设计，以不同的 URI 进行不同的操作；REST 架构下，URI 只指定资源，以 HTTP 方法动词进行不同的操作,用 HTTP STATUS / CODE 定义操作结果。

请求规范规范

http状态码

使用 HTTP 状态码定义 API 执行结果，HTTP 定义了一系列可以用在接口返回的有含义的状态码。下面是常用状态码解释：

状态码	描述	说明
200	OK	GET/POST/PUT/DELETE操作成功的状态
201	Created	POST新建数据成功的状态
204	No Content	DELETE 删除资源操作成功的状态
301	Moved Permanently	资源 URI 被转移，需要访问新的 URI
400	Bad Request	客户端一般性错误返回，在其他 4XX 以外的错误也可以用 400 返回，具体错误信息可以放在 body 中
404	Not Found	访问的资源不存在
405	Method Not Allowed	HTTP 的方法不支持，比如一些只读资源不支持POST / DELETE / PUT
429	Too Many Request	请求太频繁
500	Internal Server Error	服务器内部错误

请求方式

HTTP Method对应不同的请求动作

请求方法	说明	备注
GET	查询操作
POST	新增操作
PUT	更新操作	代表更新一个实体的所有属性
PATCH	更新操作	更新一个实体的部分属性，因为浏览器兼容性问题推荐使用PUT
DELETE	删除操作

路径规范

1.分隔符

• / 分隔符一般用来对资源层级的划分，例如 http://api.domain.com/school/classes
• 对于 REST API 来说，/ 只是一个分隔符，并无其他含义。为了避免混淆，/ 不应该出现在 URI 的末尾
• REST API 对 URI 资源的定义具有唯一性，一个资源对应一个唯一的地址。为了使接口保持清晰干净，如果访问到末尾包含 / 的地址，服务端应该 301 到没有 / 的地址上。当然这个规则也仅限于 REST API 接口的访问，对于传统的 WEB 页面服务来说，并不一定适用这个规则

2.连字符

• 连字符 - 一般用来分割 URI 中出现的字符串(单词)，来提高 URI 的可读性，例如：http://api.example.restapi.org/blogs/mark-masse/entries/this-is-my-first-post
• 使用下划线 _ 来分割字符串(单词)可能会和链接的样式冲突重叠，而影响阅读性。但实际上，- 和 _ 对 URI 中字符串的分割语意上还是有些差异的：
  • - 分割的字符串(单词)一般各自都具有独立的含义，可参见上面的例子；
  • _ 一般用于对一个整体含义的字符串做了层级的分割，方便阅读，例如你想在 URI 中体现一个 ip 地址的信息 210_110_25_88；
• 对于参数名称，使用下划线 _ 进行连接，比如 app_id

路径中统一使用小写字母

• 根据 RFC3986 定义，URI 是对大小写敏感的，所以为了避免歧义，尽量用小写字符。但主机名(Host)和 协议名称(scheme: http/ftp/…)对大小写是不敏感的。