设计RESTful风格的API
1. REST
REST(Representational State Transfer,表征性状态转移)。其与技术无关,是一种软件架构风格。
REST的六大特点:
客户端/服务器(Client/Server)
C/S架构中的关注点分离:
- 服务端专注数据存储,提升了简单性;
- 前端专注用户界面,提升了可移植性;
无状态(Stateless)
所有的用户会话信息均保存在客户端,每次请求必须包含所有信息,不能依赖上下文信息;
服务端不用保存会话信息,提升了简单性、可靠性、可见性。
缓存(Cache)
所有服务端响应都要被标记为可缓存或不可缓存。其可以减少前后端交互,提升性能。
统一接口(Uniform Interface)
接口设计尽可能统一通用,提升了简单性、可见性。
接口与实现解耦,使前后端可以独立开发迭代。
分层系统(Layered System)
每一层只能了解相邻的一层。
其他层包括:安全层、负载均衡、缓存层等等。
按需代码(Code ON Demand)
客户端可以下载运行服务端传来的代码(如JS);
其可以减少一些功能,简化客户端。
2. 统一接口限制
REST是资源的表述,资源可以是可以命名的事物,其可以是实体,也可以是抽象的概念(均用名词形式表述)。
每一个资源都可以通过URI(Uniform Resource Identifier,统一资源标识符)被唯一标识。
通过表述操作资源
表述为REST中的Representational,即资源在外界的具体呈现,因此资源可以有多种表述形式(如:JSON、XML等等),在客户端和服务端之间传输的是资源的表述。
资源的表述通常包括数据和描述数据的元数据。例如:HTTP头中的“Content-Type”为描述数据的元数据,告知客户端资源的表述形式。
因此客户端不能直接操作(如:SQL)服务端资源,应该通过表述(如:JSON)来操作服务端资源。
自描述信息
每个消息(请求或响应)必须提供足够的信息让接受者理解。如:
- 媒体类型(application/json、application/xml)
- HTTP方法(GET进行查询、POST进行新增、DELETE进行删除)
- 是否缓存(Cache-Control)
3. RESTful API
RESTful 的核心思想就是,客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如,GET /articles这个命令,GET是动词,/articles是宾语。
设计规范:
- API与客户端的通信协议,尽量使用HTTPS协议;
- 尽量将API部署在专用域名上(存在跨域问题);
- 可设置API版本;
- URL路径中,尽可能使用名词表示;
- 五种常见的请求方法;
- 通过URL上传递参数来传递搜索条件;
- 状态码(请求返回状态码);
- 错误处理(请求返回错误信息);
- 返回值(针对不同请求返回不同返回值);
- Hypermedia API;
4. 设计请求
其中动词通常为五种HTTP方法,对应对资源进行CURD操作:
- GET:读取(Read)
- POST:新建(Create)
- PUT:更新(Update)
- PETCH:部分更新(Update)
- DELETE:删除(Delete)
URL设计:
- URI使用名词,尽量使用复数,如:用户使用
/users
; - URI使用嵌套表示关联关系,如:用户admin的信息
/user/admin/info
; - 避免多级URL,除第一级,其他级别用查询字符串来进行表达;
- 可以使用
_
或者-
使URI可读性更好; - 可以使用
/
来表示资源的层级关系; - 可以使用
?
过滤资源; - 可以使用
,
、;
或者...
表示同级资源的关系;
5. 设计响应
响应部分主要由三部分组成:
- 返回状态码
- 返回信息描述
- 返回值
{
code:integer,
message:string,
data:object
}
code状态码
常见HTTP状态码:
- 200:请求成功
- 301:资源被永久转移到其它URL
- 404:请求的资源不存在
- 500:内部服务器错误
分类 | 区间 | 分类描述 |
---|---|---|
1xx | 100~199 | 相关信息:服务器收到请求 |
2xx | 200~299 | 操作成功:操作被成功接收并处理 |
3xx | 300~399 | 重定向:需要进一步操作完成请求 |
4xx | 400~499 | 客户端错误,请求包含错误或无法完成请求 |
5xx | 500~599 | 服务器错误,服务器在请求的过程中发生了错误 |
API不要1xx
状态码
2xx
表示操作成功,不同方法可以返回不同的状态码:
- GET:200 OK
- POST:201 Created
- PUT:200 OK
- PATCH:200 OK
- DELETE:204 No Content
201表示生成了新的资源;204表示资源不存在;202表示服务器收到请求,但还未进行处理,会在未来再处理,通常用于异步操作。
3xx
API用不到301状态码(永久重定向)和302状态码(暂时重定向,307也是这个含义),因为它可以由应用级别返回,浏览器可以直接跳转,API级别可以不考虑这两种情况。
API主要用到的是303状态码,它与302、307的含义一样,也就是“暂时重定向”,区别在于302和307用于PUT请求,而303用于POST、PUT和DELETE请求。收到303以后,浏览器不会自动跳转,而由用户自己决定下一步选择。
4xx
客户端错误:
- 400:服务器不理解客户端的请求,未做任何处理;
- 401:用户未提供身份验证凭据,或者没有通过身份验证;
- 403:用户通过了身份验证,但不具备访问资源所需的权限;
- 404:所请求的资源不存在或不可用;
- 405:用户已通过身份验证,但是所用的HTTP方法不在他的权限范围之内;
- 410:所请求的资源,已从此地址转移,不可再用;
- 415:客户端要求返回的格式不对;
- 422:客户端上传的附件无法处理,导致请求失败;
- 429:客户端的请求次数超过限制;
5xx
API不会向用户透露服务器的详细信息,所以只需要两个状态码:
- 500:客户端请求有效,但是服务器处理时发生了意外;
- 503:服务器无法处理请求,一般用于网站维护时;
message 返回信息描述
建议将此信息与状态码进行一一对应,便于维护。
data 返回值
通常使用JSON格式,返回数据体。