【转载】RESTful API简介

在学习RESTful 风格接口之前，即使你不知道它是什么，但你肯定会好奇它能解决什么问题？有什么应用场景？听完下面描述我想你就会明白：

随着互联网和移动设备的发展，人们对Web应用的使用需求也增加，

传统的动态页面由于低效率而渐渐被HTML+JavaScript(Ajax)的前后端分离所取代，

并且安卓、IOS、小程序等形式客户端层出不穷，客户端的种类出现多元化，

而客户端和服务端就需要接口进行通信，但接口的规范性就又成了一个问题：

所以一套结构清晰、符合标准、易于理解、扩展方便让大部分人都能够理解接受的接口风格就显得越来越重要，

而RESTful风格的接口(RESTful API)刚好有以上特点，就逐渐被实践应用而变得流行起来。

现在，RESTful是目前最流行的接口设计规范，在很多公司有着广泛的应用，其中Github 的API设计就是很标准的RESTful API，你可以参考学习。

在开发实践中我们很多人可能还是使用传统API进行请求交互，很多人其实并不特别了解RESTful API，对RESTful API的认知可能会停留在：

• 面向资源类型的
• 是一种风格
• (误区)接口传递参数使用斜杠(/)分割而不用问号(?)传参。

而其实一个很大的误区不要认为没有查询字符串就是RESTful API，也不要认为用了查询字符串就不是RESTful API，更不要认为用了JSON传输的API就是RESTful API。

本教程将带你了解RESTful并用SpringBoot实战RESTful API，在实现本案例前，你需要保证你的电脑上

• 拥有IDEA用来编写项目代码
• 拥有Postman模拟请求进行测试
• 拥有关系数据库MySQL 5.7
• 拥有navicat对MySQL进行管理

REST与RESTful API的关系

REST（英文：Representational State Transfer，简称REST，直译过来表现层状态转换）是一种软件架构风格、设计风格，而不是标准，只是提供了一组设计原则和约束条件。

它主要用于客户端和服务器交互类的软件。基于这个风格设计的软件可以更简洁，更有层次，更易于实现缓存等机制。

需要注意的是REST并没有一个明确的标准，而更像是一种设计的风格，

满足这种设计风格的程序或接口我们称之为RESTful(从单词字面来看就是一个形容词)。

所以RESTful API 就是满足REST架构风格的接口。

REST架构特征

大致有以下几个主要特征：

以资源为基础 ：资源可以是一个图片、音乐、一个XML格式、HTML格式或者JSON格式等网络上的一个实体，

除了一些二进制的资源外普通的文本资源更多以JSON为载体、面向用户的一组数据(通常从数据库中查询而得到)。

统一接口: 对资源的操作包括获取、创建、修改和删除，这些操作正好对应HTTP协议提供的GET、POST、PUT和DELETE方法。

换言而知，使用RESTful风格的接口但从接口上你可能只能定位其资源，

但是无法知晓它具体进行了什么操作，需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断。

具体的HTTP方法和方法含义如下：

• GET（SELECT）：从服务器取出资源（一项或多项）。
• POST（CREATE）：在服务器新建一个资源。
• PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）。
• PATCH（UPDATE）：在服务器更新资源（客户端提供需要修改的资源数据）。
• DELETE（DELETE）：从服务器删除资源。

当然也有很多在具体使用的时候使用PUT表示更新。从请求的流程来看，RESTful API和传统API大致架构如下：

URI指向资源：URI = Universal Resource Identifier 统一资源标志符，用来标识抽象或物理资源的一个紧凑字符串。

URI包括URL和URN，在这里更多时候可能代指URL(统一资源定位符)。

RESTful是面向资源的，每种资源可能由一个或多个URI对应，但一个URI只指向一种资源。

无状态：服务器不能保存客户端的信息， 每一次从客户端发送的请求中，要包含所有必须的状态信息，会话信息由客户端保存，

服务器端根据这些状态信息来处理请求。 当客户端可以切换到一个新状态的时候发送请求信息，

当一个或者多个请求被发送之后, 客户端就处于一个状态变迁过程中。

每一个应用的状态描述可以被客户端用来初始化下一次的状态变迁。

RESTful API设计规范

既然了解了RESTful的一些规则和特性，那么具体该怎么去设计一个RESTful API呢？要从URL路径、HTTP请求动词、状态码和返回结果等方面详细考虑。至于其他的方面例如错误处理、过滤信息等规范这里就不详细介绍了。

URL设计规范

URL为统一资源定位器 ,接口属于服务端资源，首先要通过URL这个定位到资源才能去访问，而通常一个完整的URL组成由以下几个部分构成：

URI = scheme "://" host  ":"  port "/" path [ "?" query ][ "#" fragment ]

scheme: 指底层用的协议，如http、https、ftp
host: 服务器的IP地址或者域名
port: 端口，http默认为80端口
path: 访问资源的路径，就是各种web 框架中定义的route路由
query: 查询字符串，为发送给服务器的参数，在这里更多发送数据分页、排序等参数。
fragment: 锚点，定位到页面的资源

我们在设计API时URL的path是需要认真考虑的，而RESTful对path的设计做了一些规范，通常一个RESTful API的path组成如下：

/{version}/{resources}/{resource_id}

version：API版本号，有些版本号放置在头信息中也可以，通过控制版本号有利于应用迭代。
resources：资源，RESTful API推荐用小写英文单词的复数形式。
resource_id：资源的id，访问或操作该资源。

当然，有时候可能资源级别较大，其下还可细分很多子资源也可以灵活设计URL的path，例如：

/{version}/{resources}/{resource_id}/{subresources}/{subresource_id}

此外，有时可能增删改查无法满足业务要求，可以在URL末尾加上action，例如

/{version}/{resources}/{resource_id}/action

其中action就是对资源的操作。

从大体样式了解URL路径组成之后，对于RESTful API的URL具体设计的规范如下：

1. 不用大写字母，所有单词使用英文且小写。
2. 连字符用中杠"-"而不用下杠"_"
3. 正确使用 "/"表示层级关系,URL的层级不要过深，并且越靠前的层级应该相对越稳定
4. 结尾不要包含正斜杠分隔符"/"
5. URL中不出现动词，用请求方式表示动作
6. 资源表示用复数不要用单数
7. 不要使用文件扩展名

HTTP动词

在RESTful API中，不同的HTTP请求方法有各自的含义，这里就展示GET,POST,PUT,DELETE几种请求API的设计与含义分析。针对不同操作，具体的含义如下：

GET /collection：从服务器查询资源的列表（数组）
GET /collection/resource：从服务器查询单个资源
POST /collection：在服务器创建新的资源
PUT /collection/resource：更新服务器资源
DELETE /collection/resource：从服务器删除资源

在非RESTful风格的API中，我们通常使用GET请求和POST请求完成增删改查以及其他操作，查询和删除一般使用GET方式请求，更新和插入一般使用POST请求。从请求方式上无法知道API具体是干嘛的，所有在URL上都会有操作的动词来表示API进行的动作，例如：query，add，update，delete等等。

而RESTful风格的API则要求在URL上都以名词的方式出现，从几种请求方式上就可以看出想要进行的操作，这点与非RESTful风格的API形成鲜明对比。

在谈及GET,POST,PUT,DELETE的时候，就必须提一下接口的安全性和幂等性，其中安全性是指方法不会修改资源状态，即读的为安全的，写的操作为非安全的。而幂等性的意思是操作一次和操作多次的最终效果相同，客户端重复调用也只返回同一个结果。

上述四个HTTP请求方法的安全性和幂等性如下：

状态码和返回数据

服务端处理完成后客户端也可能不知道具体成功了还是失败了，服务器响应时，包含状态码和返回数据两个部分。

状态码

我们首先要正确使用各类状态码来表示该请求的处理执行结果。状态码主要分为五大类：

1xx：相关信息
2xx：操作成功
3xx：重定向
4xx：客户端错误
5xx：服务器错误

每一大类有若干小类，状态码的种类比较多，而主要常用状态码罗列在下面：

200 OK - [GET]：服务器成功返回用户请求的数据，该操作是幂等的（Idempotent）。
201 CREATED - [POST/PUT/PATCH]：用户新建或修改数据成功。
202 Accepted -：表示一个请求已经进入后台排队（异步任务）
204 NO CONTENT - [DELETE]：用户删除数据成功。
400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。
401 Unauthorized -：表示用户没有权限（令牌、用户名、密码错误）。
403 Forbidden - 表示用户得到授权（与401错误相对），但是访问是被禁止的。
404 NOT FOUND -：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。
406 Not Acceptable - [GET]：用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。
410 Gone -[GET]：用户请求的资源被永久删除，且不会再得到的。
422 Unprocesable entity - [POST/PUT/PATCH] 当创建一个对象时，发生一个验证错误。
500 INTERNAL SERVER ERROR -：服务器发生错误，用户将无法判断发出的请求是否成功。

返回结果

针对不同操作，服务器向用户返回数据，而各个团队或公司封装的返回实体类也不同，但都返回JSON格式数据给客户端。