RESTful API 接口规范详解

RESTful API 接口规范

一、RESTful API 接口规范

REST：英文 Representational State Transfer 直译为表现层状态转移

RE(Representational) 表现层
RE(Representational) 表现层是指资源 (Resource) 的表现形式， 资源 (Resource) 指要操作的数据对象，比如用户、订单、商品、分类、文章等。用户列表是一个资源；某个具体的用户也是一个资源。表现层是指资源呈现出来的具体格式。比如同一个用户资源，可以用 JSON 格式返回给客户端，也可以用 XML 格式返回，这就是不同的表现形式。

S(State) 状态
ST(State) 状态是指资源在某一时刻的状态。比如你登录网站后，服务器会在内存中记住你是谁，之后在网站上操作就不用再次登录了，这就是有状态。而无状态就是服务器不记录客户端的任何信息，每次请求都是独立的。

T(Transfer) 转移
要注意转移是双向的，当你用 GET 请求时，服务器把资源的状态转移给客户端；当你用 POST 请求时，客户端把资源的新状态转移给服务器，从而改变服务器上资源的状态。

组合起来 REST(Representational State Transfer) 是一种软件架构风格，让客户端和服务器通过统一的接口以无状态的方式互相传递资源的表现层数据来查询或变更资源状态，而 ful 是个后缀就像 powerful 充满力量的一样，表示充满某个特性的。因此 RESTful API 是指符合 REST 架构风格的 API

注意：它不是协议，不是标准，不是强制规范，只是一种建议的设计风格，你可以遵循，也可以不遵循。

例如：你要做一个用户管理系统，对用户信息进行增删改查，用 RESTful 风格的 API，如下所示：

• GET /users/123 获取 ID 为 123 的用户
• POST /users 创建新用户
• PUT /users/123 修改用户 123
• DELETE /users/123 删除用户 123

比较

操作	非 RESTful	RESTful
获取用户	POST /getUser?id=1	GET /users/1
创建用户	POST /createUser	POST /users
更新用户	POST /update_user	PUT /users/1
删除用户	POST /delete/user	DELETE /users/1

二、构造 RESTful API

2.1 客户端发送请求

2.1.1 确定资源

资源用 URI 统一资源标识符来表示，核心规则是用名词来表示资源，不用动词。

• 名称复数表示资源集合，如：
  • /users 表示用户列表；
  • /products 表示商品列表
• 具体某个资源，就加上 ID，如：
  • /users/123 表示 ID 为 123 的用户
• 支持嵌套，如：
  • /users/123/orders 获取用户 123 的所有订单