JavaWeb基础 -- RESTful API

JavaWeb基础 – RESTful API

1. REST架构

1.1 特征简介

RESTful本身是一种风格，大致有如下几个特征：

• 以资源为基础：如图片、音频、等实体，除了一些二进制的资源外普通的文本资源更多是以JSON为载体，面向用户的一组数据。
• 统一接口：对资源的操作包括获取、创建、修改和删除，这些操作对应了HTTP中的GET、POST、PUT、DELETE方法。使用RESTful风格的接口从接口上只能定位资源，但是无法了解其中进行了如何的操作，需要具体了解其发生了什么操作动作要从其HTTP请求方法类型上进行判断。HTTP方法和含义如下：
  • GET：从服务器获取资源。
  • POST：在服务器上新建一个资源。
  • PUT：在服务器上更新资源。
  • DELETE：从服务器删除资源。
    以下是RESTful相较于传统API的框架对比：

• URI指向资源：URI即统一资源标志符，用于标识抽象或物理资源的一个紧凑字符串，其中包括URL和URN。在这里更多时候可能代指URL(统一资源定位符)。RESTful是面向资源的，每种资源可能由一个或多个URI对应，但一个URI只指向一种资源。

• 无状态：服务器无法保存当前客户端信息，每一次从客户端发送请求，包含的状态信息以及回话等均由客户端保存。服务器根据这些状态信息处理请求。 当客户端可以切换到一个新状态的时候发送请求信息， 当一个或者多个请求被发送之后, 客户端就处于一个状态变迁过程中。 每一个应用的状态描述可以被客户端用来初始化下一次的状态变迁。

1.2 REST架构限制条件

RESTful约束满足以下六个原则：

• C/S：注重客户端与服务端分离，服务端独立可更好服务于前端、安卓、IOS等客户端设备。
• 无状态：服务端不保存客户端状态，客户端保存状态信息每次请求携带状态信息。
• 可缓存性：服务端需回复是否可以缓存以让客户端甄别是否缓存提高效率。
• 统一接口：通过一定原则设计接口，降低耦合性，简化系统架构。
• 分层系统：客户端无法直接知道连接的到终端还是中间设备，分层允许你灵活的部署服务端项目。
• 按需编码：按需代码允许我们灵活的发送一些看似特殊的代码给客户端例如JavaScript代码。

2.设计规范

2.1 URL设计规范

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

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

• scheme：底层网络协议如HTTP、HTTPS等。
• host：主机IP地址。
• port：主机端口号。
• path：访问资源路径，由Web框架中的路由提供。
• query：查询字符串，发送给服务器的参数，如数据分页、排序等参数。
• fragment：锚点，定位到页面的资源。

在设计一个RESTful API时应考虑如下参数

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

• version：API版本号
• resources：资源
• resource_id：资源id

在请求的资源比较复杂时，也可以灵活设计API

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

2.2 HTTP动词

HTTP有如下几个动词分别对应不同的操作

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	非安全	幂等	写操作非安全，一次和多次删除结果一致

2.3 状态码与返回数据

2.3.1 状态码

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

• 1xx: 相关信息
• 2xx: 操作成功
• 3xx: 重定向
• 4xx: 客户端错误
• 5xx: 服务端错误
  具体到每一个状态码都有不同含义
• 200 OK - [GET]：服务器成功返回请求数据，操作为幂等。
• 201 CREATED - [POST/PUT/PATCH]：用户新建或修改成功，操作为幂等。
• 202 Accepted - [*]：表示一个请求已经进入后台排队（异步）。
• 204 NO CONTENT - [DELETE]：用户删除成功。
• 400 INVALID REQUEST - [POST/PUT/PATCH]：用户发出请求错误，服务器没有进行新建或修改数据操作，操作为幂等。
• 401 Unauthorized - [*]：无权限。
• 403 Forbidden - [*]：用户已授权但禁止访问。
• 404 NOT FOUND - [*]：用户发出请求针对不存在的记录，服务器未进行操作，操作为幂等。
• 406 Not Acceptable - [GET]：用户请求格式不可达。
• 410 Gone - [GET]：用户请求资源已删除，无法再获得。
• 422 Unprocesable entity - [POST/PUT/PATCH]：当创建一个对象时发生一个验证错误。
• 500 INTERNAL SERVER ERROR - [*]：服务器发生错误。用户无法判断发出请求是否成功。

2.3.2 返回结果

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