RESTful 架构 & RESTful API 设计指南

简介

越来越多的人开始意识到,网站即软件,而且网站是一种新型的软件。

这种"互联网软件"采用客户端/服务器模式,建立在分布式的体系上。网站开发,完全可以采用软件开发的模式。

RESTful 架构,就是目前最流行的一种互联网软件架构。它结构清晰、符合标准、易于理解、扩展方便,所以正得到越来越多网站的采用。

REST(Representational State Transfer,简称 REST)描述了一个架构样式的网络系统,比如 web 应用程序。

它首次出现在 2000 年 Roy Thomas Fielding 的博士论文中,Fielding是一个非常重要的人,他是 HTTP 协议(1.0 版和1.1 版)的主要设计者、Apache服务器软件的作者之一、Apache 基金会的第一任主席。

在目前主流的三种 Web 服务交互方案中,REST 相比于 SOAP(Simple Object Access protocol,简单对象访问协议)以及 XML-RPC 更加简单明了。

无论是对 URL 的处理还是对 Payload 的编码,REST 都倾向于用更加简单的方法来设计和实现。

值得注意的是,REST 并没有一个明确的标准,而更像是一种设计风格。

REST 原则

REST 指的是一组架构的约束条件和原则。如果一个架构符合 REST 原则,就称它为 RESTful 架构。

资源(Resources)

REST 的名称"表现层状态转化"中,省略了主语。"表现层"其实指的是"资源"(Resources)的"表现层"。

所谓"资源",就是网络上的一个实体,或者说是网络上的一个具体信息。

资源可以是文本、图片、数据库记录、算法等。每个资源都使用 URI (Universal Resource Identifier) 得到一个唯一的地址,或者说,每种资源都对应一个特定的 URI。

URI 是资源的唯一识别符,只代表网络中资源的地址(位置),而不代表资源的表现形式。

表现层(Representation)

资源是一种实体,它可以有多种表现形式。我们把资源具体呈现出来的形式,叫做它的表现层(Representation)。

资源的表现形式,可以是 html、json、xml 等,表现形式由 HTTP 请求头信息中的Accept 和 Content-Type 字段来指定。

状态转化(State Transfer)

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

HTTP 协议,是一个无状态协议。这意味着,所有的状态都保存在服务器端。

如果客户端想要操作服务器,就必须通过某种手段,让服务器端发生"状态转化"(State Transfer)。而这种转化是基于表现层的,所以就是"表现层状态转化"。

客户端用到的手段,只能是 HTTP 协议。具体来说,就是利用 HTTP 的动词来进行操作资源。

HTTP 动词

对于资源的具体操作类型,由 HTTP 动词来表示。

HTTP 动词对应的操作如下:

  • GET: 获取资源(一个或多个)。
  • POST: 创建资源。
  • PUT:更新资源(客户端提供更新后的完整资源)。
  • PATCH:更新资源(客户端提供改变的属性)。
  • DELETE:删除资源。
  • HEAD:获取资源的元数据。
  • OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。

幂等性

幂等性是指应用程序中,同一段代码多次执行和一次执行的结果完全一致。

对于上述 HTTP 动词,GET、PUT、PATCH、DELETE、HEAD 和 OPTIONS 应该是幂等的;而 POST 是非幂等的。

综述

综合上面的解释,我们总结一下什么是 RESTful 架构。

RESTful 架构遵循以下几个原则:

  • 网络中的所有实体都是资源,每一种资源都对应一个 URI。
  • 客户端和服务器之间,传递这种资源的某种表现层。
  • 客户端通过 HTTP 动词,对服务器端的资源进行操作,实现"表现层状态转化"。

RESTful API 设计指南

符合 RESTful 架构 的 API 设计,就是 RESTful API。

由于 RESTful 架构的简单性和可扩展性,RESTful 风格的 API 已经逐渐取代了 RPC 风格的 API。

通信协议

RESTful API 采用的通信协议为 http 或 https。

域名

应该尽量将 API 部署为专有域名或放在主域名下。

https://api.example.com/



https://example.com/api/

API 的版本

应该将 API 的版本号放入 URL。

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

另一种做法是,将版本号放在 HTTP 头信息中,但不如放入 URL 中方便、直观。

路径(path)

路径又称为终点(endpoint),用来表示 API 的具体名称,它是一个相对于服务器地址(https://api.example.com/v1/ )的相对路径。

在 RESTful 架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词,而且所用的名词往往与数据库的表名对应。

一般来说,数据库中的表都是同种记录的集合(collection),所以 API 中的名词也应该使用复数。

举例来说,文章 API 接口,用于提供文章相关的 API,它的路径(终点)应该设计为:

/articles

/articles/{id}

那么,API 的完整路径为:

http://apidemo.test/api/v1/articles

http://apidemo.test/api/v1/articles/{id}

HTTP 动词

对于资源的具体操作类型,由 HTTP 动词来表示。

HTTP 动词对应的操作如下:

  • GET: 获取资源(一个或多个)。
  • POST: 创建资源。
  • PUT:更新资源(客户端提供更新后的完整资源)。
  • PATCH:更新资源(客户端提供改变的属性)。
  • DELETE:删除资源。
  • HEAD:获取资源的元数据。
  • OPTIONS:获取信息,关于资源的哪些属性是客户端可以改变的。

其中,GET、POST、PUT、PATCH 和 DELETE 是最常用的五个动词。

下面是一些例子:

  • GET /articles 获取所有的文章列表
  • POST /articles 创建新文章
  • GET /articles/{id} 获取指定的文章
  • PUT /articles/{id} 更新指定的文章(提供该文章的全部信息)
  • PATCH /articles/{id} 更新指定的文章(提供该文章的部分信息)
  • DELETE /articles/{id} 删除指定的文章

过滤信息

如果记录数量太多,服务器不可能将它们一次返回给用户。API 应该提供参数,来过滤返回结果。

下面是一些常见的参数。

  • ?limit=10:指定返回记录的数量
  • ?offset=10:指定返回记录的开始位置。
  • ?page=2&per_page=100:指定第几页,以及每页的记录数。
  • ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序的顺序。
  • ?user_id=1:指定筛选条件。

状态码

服务器向客户端返回的状态码和提示信息,常见的有以下这些(方括号中是该状态码对应的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] 当创建一个对象时,发生一个验证错误。
  • 500 INTERNAL SERVER ERROR - [*]:服务器内部发生错误,用户将无法判断发出的请求是否成功。

错误处理

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

{
    error: "Invalid API key"
}

返回结果

针对不同操作,服务器向用户返回的结果应该符合以下规范。

  • GET /articles 返回文章对象列表(数组)
  • POST /articles 返回新生成的文章对象
  • GET /articles/{id} 返回单个文章对象
  • PUT /articles/{id} 返回更新后的文章对象
  • PATCH /articles/{id} 返回更新后的文章对象
  • DELETE /articles/{id} 返回空对象

数据格式

服务器返回的数据格式,应该尽量使用 JSON,避免使用 XML。

API 认证

API 的身份认证,推荐使用 OAuth 2.0 标准。

当然,你也可以使用 JWT,甚至是自定义的 api_token。

展开阅读全文

Git 实用技巧

11-24
这几年越来越多的开发团队使用了Git,掌握Git的使用已经越来越重要,已经是一个开发者必备的一项技能;但很多人在刚开始学习Git的时候会遇到很多疑问,比如之前使用过SVN的开发者想不通Git提交代码为什么需要先commit然后再去push,而不是一条命令一次性搞定; 更多的开发者对Git已经入门,不过在遇到一些代码冲突、需要恢复Git代码时候就不知所措,这个时候哪些对 Git掌握得比较好的少数人,就像团队中的神一样,在队友遇到 Git 相关的问题的时候用各种流利的操作来帮助队友于水火。 我去年刚加入新团队,发现一些同事对Git的常规操作没太大问题,但对Git的理解还是比较生疏,比如说分支和分支之间的关联关系、合并代码时候的冲突解决、提交代码前未拉取新代码导致冲突问题的处理等,我在协助处理这些问题的时候也记录各种问题的解决办法,希望整理后通过教程帮助到更多对Git操作进阶的开发者。 本期教程学习方法分为“掌握基础——稳步进阶——熟悉协作”三个层次。从掌握基础的 Git的推送和拉取开始,以案例进行演示,分析每一个步骤的操作方式和原理,从理解Git 工具的操作到学会代码存储结构、演示不同场景下Git遇到问题的不同处理方案。循序渐进让同学们掌握Git工具在团队协作中的整体协作流程。 在教程中会通过大量案例进行分析,案例会模拟在工作中遇到的问题,从最基础的代码提交和拉取、代码冲突解决、代码仓库的数据维护、Git服务端搭建等。为了让同学们容易理解,对Git简单易懂,文章中详细记录了详细的操作步骤,提供大量演示截图和解析。在教程的最后部分,会从提升团队整体效率的角度对Git工具进行讲解,包括规范操作、Gitlab的搭建、钩子事件的应用等。 为了让同学们可以利用碎片化时间来灵活学习,在教程文章中大程度降低了上下文的依赖,让大家可以在工作之余进行学习与实战,并同时掌握里面涉及的Git不常见操作的相关知识,理解Git工具在工作遇到的问题解决思路和方法,相信一定会对大家的前端技能进阶大有帮助。
©️2020 CSDN 皮肤主题: 点我我会动 设计师: 上身试试 返回首页
实付0元
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、C币套餐、付费专栏及课程。

余额充值