理解 RESTful API

一、名称

REST，即Representational State Transfer的缩写。直接翻译的意思是"表现层状态转化"。

2000年，Roy Thomas Fielding博士在他那篇著名的博士论文《Architectural Styles and the Design of Network-based Software Architectures》中提出了几种软件应用的架构风格，REST作为其中的一种架构风格在这篇论文的第5章中进行了概括性的介绍。

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

二、资源

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

所谓"资源"，就是网络上的一个实体，或者说是网络上的一个具体信息。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。你可以用一个URI（统一资源标识符）指向它，每种资源对应一个特定的URI。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。

互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，所以就是"表现层状态转化"。

三、HTTP动词

五个表示操作方式的动词：GET、POST、PUT、DELETE。
客户端通过五个HTTP动词，对服务器端资源进行操作，实现"表现层状态转化"。

它们分别对应五种基本操作：

• GET：用来获取资源
• POST：用来新建资源（也可以用于更新资源）
• PUT（UPDATE）：用来更新资源
• PATCH（UPDATE）：在服务器更新资源（客户端提供改变的属性）。
• DELETE：用来删除资源。

还有两个不常用的HTTP动词。

• HEAD：获取资源的元数据。
• OPTIONS：获取信息，关于资源的哪些属性是客户端可以改变的。发送一种“探测”请求以确定针对某个目标地址的请求必须具有怎样的约束（比如应该采用怎样的HTTP方法以及自定义的请求报头），然后根据其约束发送真正的请求

PUT大多时候表示更新该资源的全部信息，而PATCH则更新部分信息；
PUT和POST又一些功能的重叠，都可以是新建一个资源；

四、RESTful架构

url地址中只包含名词表示资源，使用http动词表示动作进行操作资源
举例说明：

// 获取所有扩展系统信息
GET /management/getExternalSystem      --> GET /management/ExternalSystem      获取所有扩展系统
                                       --> GET /management/ExternalSystem/1    获取指定扩展系统
POST /management/addExternalSystem     --> POST /management/ExternalSystem     创建扩展系统
POST /management/editExternalSystem    --> PUT /management/ExternalSystem      更新扩展系统 
GET /management/delExternalSystem?id=1 --> DELETE /management/ExternalSystem/1  删除扩展系统

使用统一的接口

五、REST的五大特性

如上的 api 设计中，首先如上的 url 设计中，通过授权码中获取登录用户 uid。则是有状态的了，其次因为所有的用户访问的资源都是同一个地址，这与唯一资源的概念是相违背的。如果是无状态的，那么就与唯一资源的概念相吻合了。

• 资源（Resource）
• 资源的表述（Representation）
• 状态转移（State Transfer）
• 统一接口（Uniform Interface）
• 超文本驱动（Hypertext Driven）

资源的概念是 RESTful 里面最重要的一个概念。

参考https://www.jianshu.com/p/6baf8554b3f4?from=timeline&isappinstalled=0