参考

• 理解RESTful架构
• RESTful API 设计指南

RESTful API

REST的由来

REST 这个词，是Roy Thomas Fielding 在他2000年的博士论文中提出的。

Fielding 将他对互联网软件的架构原则，定名为 REST，即 Representational State Transfer 的缩写，翻译为 表现层状态转化。

如果一个架构符合 REST 原则，就称它为RESTful架构。

要理解RESTful架构，最好的方法就是去理解Representational State Transfer这个词组到底是什么意思，它的每一个词代表了什么涵义。如果你把这个名称搞懂了，也就不难体会REST是一种什么样的设计。

资源(Resources)

REST名称中 表现层状态转化中，省略了主语。表现层 其实指的是 资源(Resources) 的 表现层

所谓 资源，本质上就是网络中的一个具体的信息。它可以是一段文本、一张图片、一个文件、一个API服务等。

你可以用一个 URL(统一资源定位符)指向一个具体的资源，每个资源可以对应一个或多个URI。

我们平时浏览网页本质上就是获取各种图片、视频、HTML网页等资源的集合。

表现层(Representation)

资源具体的呈现方式，称之为 表现层。

例如：一段文本可以用txt格式展示，也可以用word、html等其他格式展示。一个API返回的数据，既可以用 json格式，也可以用xml格式。

URI代表的是资源的实体，不包含它的表现形式。对于表现层的描述，可以通过HTTP请求中的Accept和Content-Type来决定。

状态转化(State Transfer)

我们通过网页上提供的各种操作来和服务端做交互，服务端最终会通过变更存储的数据以保存客户操作的结果。而 状态转化 指的就是服务端资源状态的变化并存储起来。

我们对资源的操作都是通过 HTTP 协议提供的四种基本操作：GET、POST、PUT、DELETE来进行的。

GET用于获取资源；POST用于创建资源；PUT用于更新资源；DELETE用于删除资源。

什么是RESTful架构

概念解释

符合REST原则的架构，就是RESTful架构。那么REST原则是什么呢？

主要有以下三个点：

• 每个URI代表一个资源
• 客户端与服务端之间，传递的是这种资源的表现层。例如：传递的是JSON数据，JSON数据是资源的一种呈现格式。
• 客户端通过四个HTTP动词，对服务端的资源进行操作，实现资源表现层状态转化。

总结为一句话，即 通过四个HTTP动词 传递资源的某种格式(即表现层) 来操作资源，换言之，即通过HTTP请求操作数据。

例子

RESTful架构的设计原则如下：

• 资源用复数名词或短语表示
• 用 GET/POST/PUT/DELETE 分别表示对资源的获取、新增、更新、删除

RESTFul API

RESTFul API指的是一套符合 RESTful架构的API设计理论。

API版本

将API版本号放入URL

https://api.example.com/v1/

路径(Endpoint)

路径指API的具体网址。每个网址代表一种资源，因此网址中不能有动词，只能是复数名词。名词往往与数据库的表对应。

例如：

系统有张用户表：user，那么对用户的操作应该设计成：

GET /users
POST /users
PUT /users/1  // 更新ID为1的用户
DELETE /users/1 // 删除ID为1的用户
GET /users/1/bankCards // 获取ID为1的用户的所有银行卡

接口命名对照表

以用户为例，例举各种场景：

（完）