# RESTful API 设计

REST 全称是 Representational State Transfer，中文意思是 - "表述性 状态转化"。 REST 指的是一组架构约束条件和原则。 如果一个架构符合 REST 的约束条件和原则，我们就称它为 RESTful 架构。

REST 本身并没有创造新的技术、组件或服务，而隐藏在 RESTful 背后的理念就是基于现有 Web 的特征和能力，更好地应用现有 Web 标准中的一些准则和约束。虽然 REST 本身受 Web 技术的影响很深， 但是理论上 REST 架构风格并不是绑定在 HTTP 上，只不过目前 HTTP 是唯一与 REST 相关的实例。 所以我们这里描述的 REST 也是通过 HTTP 实现的 REST。

用我的话说: "REST 是基于 Web 标准的准则和约束, 目的是为了建立功能强、性能好、适宜通信的应用程序架构, HTTP 是实现 REST 的方法之一"

# REST 名字理解

"表述性 状态转化" - 到底什么意思 ?

这个名字其实省略了主语。"表述性" 指的是 "资源" 的 "表述性"。所谓 "资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的 URI。URI 就成了每一个资源的地址或独一无二的识别符.

"资源" 是一种信息实体，它可以有多种外在表现形式。我们把 "资源" 具体呈现出来的形式，叫做它的 "表述". 比如，文本可以用 txt 格式表现，也可以用 HTML 格式、XML 格式、JSON 格式表现，甚至可以采用二进制格式；图片可以用 JPG 格式表现，也可以用 PNG 格式表现。URI 应该只代表 "资源" 的位置。它的具体表现形式，应该在 HTTP 请求的头信息中用 Accept 和 Content-Type 字段指定，这两个字段才是对 "表述" 的描述。

访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，势必涉及到数据和状态的变化。HTTP 协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生 "状态转化"。而这种转化是建立在表述层之上的，所以就是 "表述性状态转化"。

在前端开发中, 客户端的手段就是 HTTP 方法, 四个表示操作方式的动词：GET、POST、PUT、DELETE。它们分别对应四种基本操作：

• GET 用来获取资源
• POST 用来新建资源（也可以用于更新资源）
• PUT 用来更新资源
• DELETE 用来删除资源

综合上面的解释，我们总结一下什么是 RESTful 架构：

1. 每一个 URI 代表一种资源；
2. 客户端和服务器之间，传递这种资源的某种表述
3. 客户端通过 HTTP 动词，对服务器端资源进行操作，实现 "表述性状态转化"。

# 接口文档示例

# 用户列表

用于获取用户列表，带分页功能

# 接口：

GET /users

# 请求参数：

# 响应：

成功：200

响应格式：JSON

{
    totalCount: {number}, // 总数
    results: [
        {
            "id": {number},
            "name": {string},
            "role": [{number}, ...], // 角色，多个角色用数组表示
            "birthday": {string}, // 生日使用YYYYMMDD格式
        },
        ...
    ]
}