后端开发必备的 RestFul API 知识 _API

文章插图
RestFul API 是每个程序员都应该了解并掌握的基本知识，我们在开发过程中设计API的时候也应该至少要满足RestFul API的最基本的要求（比如接口中尽量使用名词，使用POST 请求创建资源，DELETE请求删除资源等等，示例：GET /notes/id：获取某个指定id的笔记的信息）。最近学习过程中接触到这些东西，自己没有时间总结，所以分享一些不错的文章给大家。
相关阅读：
•http://www.ruanyifeng.com/blog/2014/05/restful_api.html（阮一峰，这篇文章大部分内容来源）
•https://www.baeldung.com/spring-hateoas-tutorial(RestFul API Tutorial)
•https://aisensiy.github.io/2017/06/04/spring-boot-and-hateoas/(Spring中使用HATEOAS)
•https://spring.io/guides/tutorials/bookmarks/ (Building REST services with Spring)
•https://www.baeldung.com/spring-hateoas-tutorial(https://www.baeldung.com/spring-hateoas-tutorial)
备注：HATEOAS这个大家可能之前并没有怎么接触过，我看了很多项目的源码也并没有满足HATEOAS设计的要求，实际上RestFul API 最好满足HATEOAS设计，也就是在返回结果中提供链接，连向其他API方法，使得用户不查文档，也知道下一步应该做什么。
一、重要概念：
REST,即Representational State Transfer的缩写，翻译过来就是"表现层状态转化" 。

Resource（资源）：对象的单个实例。例如，一只动物。它可以是一段文本、一张图片、一首歌曲、一种服务，总之就是一个具体的实在。你可以用一个URI（统一资源定位符）指向它，每种资源对应一个特定的URI 。要获取这个资源，访问它的URI就可以，因此URI就成了每一个资源的地址或独一无二的识别符。
集合：对象的集合。例如，动物。
第三方：使用我们接口的开发者
表现层（Representation）："资源"是一种信息实体，它可以有多种外在表现形式。我们把"资源"具体呈现出来的形式，叫做它的"表现层"（Representation）。
状态转化（State Transfer）访问一个网站，就代表了客户端和服务器的一个互动过程。在这个过程中，势必涉及到数据和状态的变化。互联网通信协议HTTP协议，是一个无状态协议。这意味着，所有的状态都保存在服务器端。因此，如果客户端想要操作服务器，必须通过某种手段，让服务器端发生"状态转化"（State Transfer）。而这种转化是建立在表现层之上的，所以就是"表现层状态转化" 。

综合上面的解释，我们总结一下什么是RESTful架构：
（1）每一个URI代表一种资源；
（2）客户端和服务器之间，传递这种资源的某种表现层；
（3）客户端通过HTTP动词(GET,POST等等)，对服务器端资源进行操作，实现"表现层状态转化" 。
二、REST接口规范
1、动作

GET （SELECT）：从服务器检索特定资源，或资源列表。
POST （CREATE）：在服务器上创建一个新的资源。
PUT （UPDATE）：更新服务器上的资源（客户端提供更新后的整个资源）。
PATCH （UPDATE）：更新服务器上的资源（客户端提供更改的属性，可以看做作是部分更新）。
DELETE （DELETE）：从服务器删除资源。

2、路径（接口命名）
路径又称"终点"（endpoint），表示API的具体网址。
在RESTful架构中，每个网址代表一种资源（resource），所以网址中不能有动词，只能有名词，而且所用的名词往往与数据库的表格名对应。一般来说，数据库中的表都是同种记录的"集合"（collection），所以API中的名词也应该使用复数。
举例来说，有一个API提供动物园（zoo）的信息，还包括各种动物和雇员的信息，则它的路径应该设计成下面这样。
接口尽量使用名词，禁止使用动词，下面是一些例子。
GET /zoos：列出所有动物园
POST /zoos：新建一个动物园
GET /zoos/ID：获取某个指定动物园的信息
PUT /zoos/ID：更新某个指定动物园的信息（提供该动物园的全部信息）
PATCH /zoos/ID：更新某个指定动物园的信息（提供该动物园的部分信息）
DELETE /zoos/ID：删除某个动物园
GET /zoos/ID/animals：列出某个指定动物园的所有动物
DELETE /zoos/ID/animals/ID：删除某个指定动物园的指定动物复制代码
反例：
/getAllCars
/createNewCar
/deleteAllRedCars复制代码
再比如，某个URI是/posts/show/1，其中show是动词，这个URI就设计错了，正确的写法应该是/posts/1，然后用GET方法表示show 。