1、定义
RESTFUL是一种网络应用程序的设计风格和开发方式，基于HTTP，可以使用XML格式定义或JSON格式定义。REST并没有绑定到HTTP。RESTFUL API是为“资源”而实现的，“资源”可以是实体或服务。资源用表一个唯一的URI（Universal Resource Identifier）表示，资源的状态通过HTTP动词表示（GET、PUT、POST、DELETE）
2、规范
- 使用名词
因为代表的是“资源”，/createUser 替代为 /users
- 建议用复数
一个用户：GET /users/123
用户集合：GET /users
- 让HTTP动词定义动作
- 不要乱用安全（幂等）的方法
如Get多次调用应该是返回同样的值，让Get去删除就是属于乱用（多次调用返回的结果不一致）GET /users/123/delete
- 通过URI描述资源层次结构
/users/123/posts/1
- 添加API版本
版本确保API可以向后兼容实现：
自定义header 头，如X-API-VERSION=1.1；
直接放Accept头中，如Accept: application/xxx.v2+jsonURL —— 推荐做法，因为可以肉眼发现不同POST /v2/users
- 返回资源的表示形式即URI
如POST添加了新的资源，应该返回HTTP状态码201以及Location头中新创建资源的URI
- 过滤、搜索&排序
过滤 ——GET /users/123/posts?state=published
搜索 ——GET /users/123/posts?state=published&ta=scala
This will search posts for free text “sometext”(q) and filter results on fq state as published and having tag Scala.
排序 ——GET /users/123/posts?sort=-updated_at，- 代表降序，+ 代表升序
- 超媒体作为应用状态的引擎Hypermedia As Transfer Engine Of Application State
它提供了通过资源及其可用操作进行导航的便利。通过这种方式，客户机不需要知道如何与应用程序进行不同操作的交互，因为所有元数据都将嵌入到来自服务器的响应中。如 GET /users/123 对应的结果：{ “name”: “John Doe”, “links”: [ { “rel”: “self”, “href”: “http://localhost:8080/users/123" },
- “身份验证和授权”是无状态
REST API本身是无状态的，授权可通过JWT或OAuth2（注：JWT与OAuth2不是同一个东西）
- Swagger作为文档工具
- 使用HTTP状态码向客户端提供响应
3、参考
REST: Good Practices for API Design
https://medium.com/hashmapinc/rest-good-practices-for-api-design-881439796dc9
Richardson Maturity Model