RESTful API规范

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动词定义动作 

RESTful API规范

  • 不要乱用安全(幂等)的方法

如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

https://restfulapi.net/richardson-maturity-model/

RESTful API规范

上一篇:Java实现简易的文件的迁移器


下一篇:自制病毒——控制桌面鼠标以及开关机