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格式数据给客户端。