资讯专栏INFORMATION COLUMN

上云采购季！| 爆款云服务器低至4.6元/月，首单享0.9折

免费试用
首页/文章专栏/理解 RESTful

理解 RESTful

MkkHou / 2798人阅读

摘要：表形容词，意为的具有的。指的是一组架构约束条件和原则。协议要优于协议。的操作方法在中有各自的语义，理解它们的语义至为重要。返回结果对于不同操作方法和操作对象集合或个体，服务器返回的结果应该符合以下规范。附录该文主要参考理解架构设计指南

前言

近十年，前端高速发展，整个互联网应用经历了从轻客户端到重客户端的变化，随着前端规模越来越大，交互越来越复杂，前后端分离的设计开始流行。

移动互联网时代的到来，前端开始泛指各种终端和 web 前端，服务端为多终端提供服务已然成常态。

前后端分离后，前端和后端通过双方协商好的 API 进行交互，所以设计一套友好的 API 尤其重要。

RESTful 就是目前最流行的前后端交互 API 设计范式。

RESTful 释义

顾名思义，先看一下 RESTful 的单词拆解:

RESTful  =  Resources + Representation + State + Transfer + ful

我的理解是， RESTful 是指具有 资源表现层 和 状态转换 的架构设计。

资源(Resources) 
资源，是指服务端向外提供的服务实体。

资源是一个抽象的概念，可以是应用程序对象、数据库记录、算法等等。每一个资源用一个 URI 来唯一标识，客户端通过这个标识对资源进行访问、操作或请求服务。

表现层(Representation) 
表现层，是指资源的表现形式。

一个资源可以有多种表现形式。例如，文本数据可以用 XML 格式、JSON 格式表现，甚至可以用二进制格式表示；图片可以用 JPG 格式表现，也可以用 PNG 格式表现。

状态(State) 
状态，是指资源的某种状态。

一个资源可能有多种状态。例如，资源空闲的、占用的、共享的、存在的、不存在的等。

转化(Transfer) 
转化，是指对资源的操作行为。

转化的行为包括两种:

资源表现层的转化

资源状态的转化

ful 
后缀是英文的一种重要构词法，通过后缀常常可以判断出一个词的词性。

ful 表形容词，意为“... 的”、“具有 ... 的”。

小结

RESTful 是一种抽象的、与具体程序语言和网络协议无关的网络服务系统的架构样式。

它把在服务器端的数据和功能设计成各种的资源，并且通过 URI 定位资源、转化资源表现和状态的一种服务架构设计。

RESTful WEB 
REST 指的是一组架构约束条件和原则。满足这些约束条件和原则的应用程序或设计就是 RESTful。

目前 RESTful 应用最多的是在 web 服务，在 RESTful Web 服务中，每个资源都有一个地址(URL)。资源是方法调用的目标，方法列表对所有资源都是一样的。这些方法是 Http 标准方法，如 HTTP GET、POST、PUT、DELETE 等。

下面来描述一下 RESTful Web API 的一些设计原则。

通信协议 
数据传输，安全第一。

HTTPS 协议要优于 HTTP 协议。

API 的根 URL 
API 的根 URL 很重要，它应该设计成可以轻松区别于其他非 API 的 URL。

最好的做法是将 API 部署在专有的域名下。

https://api.example.com

退而求其次，分配一个域名一级目录给 API。

https://example.org/api/
版本信息 
为了 API 演变和兼容，为 API 加入版本信息是明智之举。

应该为 API 设定版本号，并把版本号信息加入到 API 的根 URL 的下一级路径。

https://api.example.com/v1/

或

https://example.org/api/v1/
URL 末端 
API 的根 URL + 版本信息 + URL 末端 = 资源位置

URL 末端最终明确指定了一个资源或一种资源的集合。URL 末端中不应该出现动词，只能是名词。如果该资源可以取其集合，对应的名词应该采用复数形式。

举个例子，有一组 API 提供公司员工的信息。

那么，获取所有员工信息，末端应该设计成 /employees, 即:

https://api.example.com/v1/employees

获取员工编号 007 员工的信息，末端应该设计成 /employees/007, 即:

https://api.example.com/v1/employees/007
操作资源 
资源的操作无外乎增、删、改、查，对应即是 HTTP 的各个操作方法。

HTTP的操作方法在 RESTful 中有各自的语义，理解它们的语义至为重要。

方法 语义 例子 说明
GET 选择、获取 GET /employees/007 获取编号 007 员工的信息
POST 新建 POST /employees 新建一个员工的信息
PUT 更新(完整) PUT /employees/007 更新编号 007 员工的全部信息，客户端提供该员工的全部信息
PATCH 更新(局部) PATCH /employees/007 更新编号 007 员工的部分信息，客户端只提供该员工的部分信息
DELETE 删除 DELETE /employees/007 删除编号 007 员工的信息
HEAD 获取(元数据) HEAD /employees/007 获取编号 007 员工的元数据，如员工数据的哈希值或最后修改时间
OPTIONS 获取(权限信息) OPTIONS /employees/007 获取客户端能编号 007 员工进行哪些操作，即操作的权限

本章中，自此以上讲述的都是如何描述"资源(Resources)"，而这小节讲述的是"转化(Transfer)"，转化资源的状态。

另外，转化还包括资源的"表现层(Representation)"，它是通过 HTTP 头部 Content Type 指定的。

过滤资源 
如果资源很多，通常你不会希望服务端一次性全部的数据，API 应该提供过滤资源的能力。

这里资源过滤依靠 URL 的查询参数，通常放置在 GET 请求的URL中。

?limit=10: 限制返回的资源数量

?offset=10: 指定返回的资源的开始位置

?sortby=name&order=asc: 对资源按特定属性进行排序

状态码 
状态码用以反映资源的操作结果或所处状态。

HTTP 状态码本身是具有语义的，这刚好配对了 RESTful 的状态。

以下列举常用的状态码:

状态码 语义 HTTP 方法 说明
200 OK GET 成功返回用户请求的数据
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 当创建一个对象时，发生一个验证错误
错误处理

如果状态码是4xx，就应该向用户返回出错信息。一般来说，返回的信息中将error作为键名，出错信息作为键值。

{
    error: "param error"
}
返回结果

对于不同操作方法和操作对象(集合或个体)，服务器返回的结果应该符合以下规范。

示例 返回
GET /collection 返回资源对象的列表（数组）
GET /collection/resource 返回单个资源对象
POST /collection 返回新生成的资源对象
PUT /collection/resource 返回完整的资源对象
PATCH /collection/resource 返回完整的资源对象
DELETE /collection/resource 返回一个空文档

另外，返回的数据格式(Representation)应该尽量使用JSON。

最后

在 RESTful WEB 的实现中，使用 URL 定位资源，HTTP 方法操作资源，使得语义明确、结构清晰、易于理解和扩展。

RESTful 的这些优势，使得它成为了目前最流行的一种互联网服务架构。

附录

该文主要参考:

Principles of good RESTful API Design

理解RESTful架构

RESTful API 设计指南

混合云 服务器托管 RESTful RESTful框架 js restful 安全 flask-restful

文章版权归作者所有，未经允许请勿转载,若此文章存在违规行为，您可以联系管理员删除。

转载请注明本文地址：https://www.ucloud.cn/yun/11772.html

相关文章

  • 理解 RESTful

    摘要：表形容词，意为的具有的。指的是一组架构约束条件和原则。协议要优于协议。的操作方法在中有各自的语义，理解它们的语义至为重要。返回结果对于不同操作方法和操作对象集合或个体，服务器返回的结果应该符合以下规范。附录该文主要参考理解架构设计指南 前言 近十年，前端高速发展，整个互联网应用经历了从轻客户端到重客户端的变化，随着前端规模越来越大，交互越来越复杂，前后端分离的设计开始流行。 移动互联网...

    Drummor 评论0 收藏0

  • RESTful实践（具体应用）思考

    摘要：其他交互一般会遵循一些数据结构协议或者状态值，比如不同的操作结果对应不同的状态值，且出错会返回指定的错误信息方便前端进行提示等。 RESTful这种架构已经具有很长的时间和历程了，但似乎最近restful这个词出现的频率特别高，目前不是很清楚是因为我自个儿现在是以restful风格写程序产生的孕妇效应，还是单页面程序开发的流行造成的。 其实一开始我也是不想写这篇文章的，因为网络上与re...

    myshell 评论0 收藏0

  • RESTful API的理解

    摘要：它的理论比较抽象不太具体，理解它主要在于理解这些概念资源表现层状态转换。基于原则设计的，一般称为，需要遵守以下这些原则。返回结果，结果应该包括多种情况，异常错误信息正确结果目前而言最好使用格式传输数据。参考的理解，阮一峰 RESTful API 目前的异步加载横行的时候，异步请求已经遍地都是，而规定请求接口的时候，如果不能有很好的风格的话，很多时候会让开发者误解，一个好的API接口 设...

    willin 评论0 收藏0

  • PHP / Laravel API 开发推荐阅读清单

    showImg(https://segmentfault.com/img/bV6aHV?w=1280&h=800); 社区优秀文章 Laravel 5.5+passport 放弃 dingo 开发 API 实战，让 API 开发更省心 - 自造车轮。 API 文档神器 Swagger 介绍及在 PHP 项目中使用 - API 文档撰写方案 推荐 Laravel API 项目必须使用的 8 个...

    shmily 评论0 收藏0

  • 理解RESTful架构与json-server模拟REST api的使用

    摘要：一什么是架构即的缩写，我们把他翻译为表述性状态传递，是博士在年他的博士论文中提出来的一种软件架构风格。是个无状态的协议，所以状态就保存在服务器端。只要少量的数据就可使用，支持和。同时支持，同时提供一系列的查询方法如。 一、什么是RESTful架构？ REST即Representational State Transfer的缩写，我们把他翻译为表述性状态传递，是Roy Fielding博...

    Atom 评论0 收藏0

发表评论

登陆后可评论

0条评论

MkkHou

男|高级讲师
我要私信

TA的文章

阅读更多

云社区相关服务

提问 提问 学习 学习 认证 认证 产品 产品 技术服务 技术服务 售前咨询 售前咨询
最新活动
阅读需要支付1元查看
<