关于程序员:Restful-API-接口设计标准及规范

53次阅读

共计 2166 个字符,预计需要花费 6 分钟才能阅读完成。

RESTful 概念

了解和评估以网络为根底的应用软件的架构设计,失去一个性能强、性能好、合适通信的架构。REST 指的是一组架构约束条件和准则。” 如果一个架构合乎 REST 的约束条件和准则,咱们就称它为 RESTful 架构。

REST 自身并没有发明新的技术、组件或服务,而暗藏在 RESTful 背地的理念就是应用 Web 的现有特色和能力,更好地应用现有 Web 规范中的一些准则和束缚。尽管 REST 自身受 Web 技术的影响很深,然而实践上 REST 架构格调并不是绑定在 HTTP 上,只不过目前 HTTP 是惟一与 REST 相干的实例。所以咱们这里形容的 REST 也是通过 HTTP 实现的 REST。

RestfulAPI 导图

了解 RESTful

要了解 RESTful 架构,须要了解 Representational State Transfer 这个词组到底是什么意思,它的每一个词都有些什么涵义。咱们围绕资源展开讨论,从资源的定义、获取、表述、关联、状态变迁等角度,列举一些要害概念并加以解释。

  • 资源与 URI
  • 对立资源接口
  • 资源的表述
  • 资源的链接
  • 状态的转移

资源与 URI

URI 示意资源,资源个别对应服务器端畛域模型中的实体类

  • URI 是地址也是资源
  • URI 里边带上版本号、后缀来辨别表述格局
  • 必备约定

    • 用名词、不必动词
    • 层级构造明确、用 / 来示意
    • 用? 用来过滤资源

对立资源接口

规范 HTTP 办法蕴含:GET、POST、PUT、DELETE、Patch,他们的应用性能如下列表所示

<center>

</center>

Get 办法执行流程原理如下所示

<center>

</center>

Put 办法执行流程图如下所示

<center>

</center>

安全性和幂等性

  • 1、安全性:不会扭转资源状态,能够了解为只读的;
  • 2、幂等性:执行 1 次和执行 N 次,对资源状态扭转的成果是等价的。
接口 安全性 幂等性
GET
POST××
PUT×
DELETE×

安全性和幂等性均不保障重复申请能拿到雷同的 response。以 DELETE 为例,第一次 DELETE 返回 200 示意删除胜利,第二次返回 404 提醒资源不存在,这是容许的。

资源的表述

什么是资源?什么是表述?

就实质而言,任何足够重要并被援用的事物都能够是资源。如果你的用户“想要建设指向它的超文本链接,指出或者拥护对于它的断言,获取或者缓存它的表述,共另外的表述援用它的全副或者局部,给它减少正文信息,或者对它执行某些操作”,(源自《万维网的架构》),你都应该将它定义为资源。

每个资源必须领有 URL,在 web 上,咱们应用 URL 来为每个资源提供一个寰球惟一的地址,将一个事物赋以 URL,它就会成为一个资源。

石榴能够是一个资源,然而你不可能通过互联网传输它,数据库中的一条记录能够是一个资源,并且能够通过互联网传输。

当客户端对一个资源发动一个 Get 申请的时候,服务器会以一种无效的形式提供一个采集了资源信息的文档作为回应。这种资源信息的文档就是一种表述,一种以机器可读的形式对资源以后的状态进行阐明

资源有多重表述

一个资源能够有多种表述。比方,有的资源能够有整体概括性的表述,也能够有八面玲珑的具体表述,又或者可能以 JSON 格局或者 XML 格局来表述同一个资源。

资源的连贯

咱们晓得 REST 是应用规范的 HTTP 办法来操作资源的,但仅仅因而就了解成带 CURD 的 Web 数据库架构就太过于简略了。

这种反模式疏忽了一个外围概念:” 超媒体即利用状态引擎(hypermedia as the engine of application state)”。超媒体是什么?

当你浏览 Web 网页时,从一个连贯跳到一个页面,再从另一个连贯跳到另外一个页面,就是利用了超媒体的概念:把一个个把资源链接起来.

要达到这个目标,就要求在表述格局里边退出链接来疏导客户端。在《RESTful Web Services》一书中,作者把这种具备链接的个性成为连通性。上面咱们具体来看一些例子。

上面展现的是 github 获取某个组织下的我的项目列表的申请,能够看到在响应头里边减少 Link 头通知客户端怎么拜访下一页和最初一页的记录。而在响应体里边,用 url 来链接我的项目所有者和我的项目地址。

下面的例子展现了如何应用超媒体来加强资源的连通性。很多人在设计 RESTful 架构时,应用很多工夫来寻找丑陋的 URI,而疏忽了超媒体。所以,应该多花一些工夫来给资源的表述提供链接,而不是专一于 ” 资源的 CRUD”。

状态的转移

拜访一个网站,就代表了客户端和服务器的一个互动过程。在这个过程中,势必波及到数据和状态的变动;

互联网通信协议 HTTP 协定,是一个无状态协定。这意味着,所有的状态都保留在服务器端。因而,如果客户端想要操作服务器,必须通过某种伎俩,让服务器端产生 ” 状态转化 ”(State Transfer)。而这种转化是建设在体现层之上的,所以就是 ” 体现层状态转化 ”;

客户端用到的伎俩,只能是 HTTP 协定。具体来说,就是 HTTP 协定外面,四个示意操作形式的动词:GET、POST、PUT、DELETE。它们别离对应四种基本操作:GET 用来获取资源,POST 用来新建资源(也能够用于更新资源),PUT 用来更新资源,DELETE 用来删除资源;

## 博主 GitHub 地址
https://github.com/yuyue5945

关注公众号不迷路

<center>

</center>

正文完
 0