浅谈RESTful
浅谈RESTful
什么是RESTful?
REST全称是Representational State Transfer,中文意思是表述(编者注:通常译为表征)性状态转移。 它首次出现在2000年Roy Fielding的博士论文中,Roy Fielding是HTTP规范的主要编写者之一。 他在论文中提到:"我这篇文章的写作目的,就是想在符合架构原理的前提下,理解和评估以网络为基础的应用软件的架构设计,得到一个功能强、性能好、适宜通信的架构。REST指的是一组架构约束条件和原则。" 如果一个架构符合REST的约束条件和原则,我们就称它为RESTful架构。
REST本身并没有创造新的技术、组件或服务,而隐藏在RESTful背后的理念就是使用Web的现有特征和能力, 更好地使用现有Web标准中的一些准则和约束。虽然REST本身受Web技术的影响很深, 但是理论上REST架构风格并不是绑定在HTTP上,只不过目前HTTP是唯一与REST相关的实例。 所以我们这里描述的REST也是通过HTTP实现的REST。
REST全称是表述性状态转移,那究竟指的是什么的表述? 其实指的就是资源。任何事物,只要有被引用到的必要,它就是一个资源。资源可以是实体(例如手机号码),也可以只是一个抽象概念(例如价值) 。
要让一个资源可以被识别,需要有个唯一标识,在Web中这个唯一标识就是URI(Uniform Resource Identifier)。
URI既可以看成是资源的地址,也可以看成是资源的名称。如果某些信息没有使用URI来表示,那它就不能算是一个资源, 只能算是资源的一些信息而已。URI的设计应该遵循可寻址性原则,具有自描述性,需要在形式上给人以直觉上的关联。这里以github网站为例,给出一些还算不错的URI:
- https://github.com/git
- https://github.com/git/git
- https://github.com/git/git/blob/master/block-sha1/sha1.h
- https://github.com/git/git/commit/e3af72cdafab5993d18fae056f87e1d675913d08
- https://github.com/git/git/pulls
- https://github.com/git/git/pulls?state=closed
- https://github.com/git/git/compare/master…next
设计规范
一.url设计
1.1动词加宾语
RESTful 的核心思想就是,客户端发出的数据操作指令都是"动词 + 宾语"的结构。比如,GET /articles
这个命令,GET
是动词,/articles
是宾语。
动词通常就是五种 HTTP 方法,对应 CRUD 操作。
- GET:读取(Read)
- POST:新建(Create)
- PUT:更新(Update)
- PATCH:更新(Update),通常是部分更新
- DELETE:删除(Delete)
根据 HTTP 规范,动词一律大写。
1.2动词的覆盖
有些客户端只能使用GET
和POST
这两种方法。服务器必须接受POST
模拟其他三个方法(PUT
、PATCH
、DELETE
)。
这时,客户端发出的 HTTP 请求,要加上X-HTTP-Method-Override
属性,告诉服务器应该使用哪一个动词,覆盖POST
方法。
POST /api/Person/4 HTTP/1.1
X-HTTP-Method-Override: PUT
上面代码中,X-HTTP-Method-Override
指定本次请求的方法是PUT
,而不是POST
。
1.3宾语必须是名词
宾语就是 API 的 URL,是 HTTP 动词作用的对象。它应该是名词,不能是动词。比如,/articles
这个 URL 就是正确的,而下面的 URL 不是名词,所以都是错误的。
- /getAllCars
- /createNewCar
- /deleteAllRedCars
1.4复数url
既然 URL 是名词,那么应该使用复数,还是单数?
这没有统一的规定,但是常见的操作是读取一个集合,比如GET /articles
(读取所有文章),这里明显应该是复数。
为了统一起见,建议都使用复数 URL,比如GET /articles/2
要好于GET /article/2
。
1.5 避免多级 URL
常见的情况是,资源需要多级分类,因此很容易写出多级的 URL,比如获取某个作者的某一类文章。
GET /authors/12/categories/2
这种 URL 不利于扩展,语义也不明确,往往要想一会,才能明白含义。
更好的做法是,除了第一级,其他级别都用查询字符串表达。
GET /authors/12?categories=2
下面是另一个例子,查询已发布的文章。你可能会设计成下面的 URL。
GET /articles/published
查询字符串的写法明显更好。
GET /articles?published=true
二.状态码
2.1 状态码必须精确
客户端的每一次请求,服务器都必须给出回应。回应包括 HTTP 状态码和数据两部分。
HTTP 状态码就是一个三位数,分成五个类别。
1xx
:相关信息2xx
:操作成功3xx
:重定向4xx
:客户端错误5xx
:服务器错误
这五大类总共包含100多种状态码,覆盖了绝大部分可能遇到的情况。每一种状态码都有标准的(或者约定的)解释,客户端只需查看状态码,就可以判断出发生了什么情况,所以服务器应该返回尽可能精确的状态码。
API 不需要1xx
状态码,下面介绍其他四类状态码的精确含义。
2.2 2xx 状态码
200
状态码表示操作成功,但是不同的方法可以返回更精确的状态码。
- GET: 200 OK
- POST: 201 Created
- PUT: 200 OK
- PATCH: 200 OK
- DELETE: 204 No Content
上面代码中,POST
返回201
状态码,表示生成了新的资源;DELETE
返回204
状态码,表示资源已经不存在。
此外,202 Accepted
状态码表示服务器已经收到请求,但还未进行处理,会在未来再处理,通常用于异步操作。下面是一个例子。
HTTP/1.1 202 Accepted {
"task": {
"href": "/api/company/job-management/jobs/2130040",
"id": "2130040"
}
}
2.3 3xx 状态码
API 用不到301
状态码(永久重定向)和302
状态码(暂时重定向,307
也是这个含义),因为它们可以由应用级别返回,浏览器会直接跳转,API 级别可以不考虑这两种情况。
API 用到的3xx
状态码,主要是303 See Other
,表示参考另一个 URL。它与302
和307
的含义一样,也是"暂时重定向",区别在于302
和307
用于GET
请求,而303
用于POST
、PUT
和DELETE
请求。收到303
以后,浏览器不会自动跳转,而会让用户自己决定下一步怎么办。下面是一个例子。
HTTP/1.1 303 See Other
Location: /api/orders/12345
2.4 4xx 状态码
4xx
状态码表示客户端错误,主要有下面几种。
400 Bad Request
:服务器不理解客户端的请求,未做任何处理。
401 Unauthorized
:用户未提供身份验证凭据,或者没有通过身份验证。
403 Forbidden
:用户通过了身份验证,但是不具有访问资源所需的权限。
404 Not Found
:所请求的资源不存在,或不可用。
405 Method Not Allowed
:用户已经通过身份验证,但是所用的 HTTP 方法不在他的权限之内。
410 Gone
:所请求的资源已从这个地址转移,不再可用。
415 Unsupported Media Type
:客户端要求的返回格式不支持。比如,API 只能返回 JSON 格式,但是客户端要求返回 XML 格式。
422 Unprocessable Entity
:客户端上传的附件无法处理,导致请求失败。
429 Too Many Requests
:客户端的请求次数超过限额。
2.5 5xx 状态码
5xx
状态码表示服务端错误。一般来说,API 不会向用户透露服务器的详细信息,所以只要两个状态码就够了。
500 Internal Server Error
:客户端请求有效,服务器处理时发生了意外。
503 Service Unavailable
:服务器无法处理请求,一般用于网站维护状态。
三、服务器回应
3.1 不要返回纯本文
API 返回的数据格式,不应该是纯文本,而应该是一个 JSON 对象,因为这样才能返回标准的结构化数据。所以,服务器回应的 HTTP 头的Content-Type
属性要设为application/json
。
客户端请求时,也要明确告诉服务器,可以接受 JSON 格式,即请求的 HTTP 头的ACCEPT
属性也要设成application/json
。下面是一个例子。
GET /orders/2 HTTP/1.1
Accept: application/json
3.2 发生错误时,不要返回 200 状态码
有一种不恰当的做法是,即使发生错误,也返回200
状态码,把错误信息放在数据体里面,就像下面这样。
HTTP/1.1 200 OK
Content-Type: application/json {
"status": "failure",
"data": {
"error": "Expected at least two items in list."
}
}
上面代码中,解析数据体以后,才能得知操作失败。
这张做法实际上取消了状态码,这是完全不可取的。正确的做法是,状态码反映发生的错误,具体的错误信息放在数据体里面返回。下面是一个例子。
HTTP/1.1 400 Bad Request
Content-Type: application/json {
"error": "Invalid payoad.",
"detail": {
"surname": "This field is required."
}
}
3.3 提供链接
API 的使用者未必知道,URL 是怎么设计的。一个解决方法就是,在回应中,给出相关链接,便于下一步操作。这样的话,用户只要记住一个 URL,就可以发现其他的 URL。这种方法叫做 HATEOAS。
举例来说,GitHub 的 API 都在 api.github.com 这个域名。访问它,就可以得到其他 URL。
{
...
"feeds_url": "https://api.github.com/feeds",
"followers_url": "https://api.github.com/user/followers",
"following_url": "https://api.github.com/user/following{/target}",
"gists_url": "https://api.github.com/gists{/gist_id}",
"hub_url": "https://api.github.com/hub",
...
}
上面的回应中,挑一个 URL 访问,又可以得到别的 URL。对于用户来说,不需要记住 URL 设计,只要从 api.github.com 一步步查找就可以了。
HATEOAS 的格式没有统一规定,上面例子中,GitHub 将它们与其他属性放在一起。更好的做法应该是,将相关链接与其他属性分开。
HTTP/1.1 200 OK
Content-Type: application/json {
"status": "In progress",
"links": {[
{ "rel":"cancel", "method": "delete", "href":"/api/status/12345" } ,
{ "rel":"edit", "method": "put", "href":"/api/status/12345" }
]}
}
四、参考链接
- RESTful API Design: 13 Best Practices to Make Your Users Happy, by Florimond Manca
- API design, by MicroSoft Azure
RESTful API 最佳实践,阮一峰的网络日志
(完)
浅谈RESTful的更多相关文章
- [01] 浅谈RESTful风格的API
1.什么是RESTful风格的API REST,即Representational State Transfer,可以理解为"(资源的)表现层状态转化". 在网络上,我们通过浏览器 ...
- Web Service进阶(七)浅谈SOAP Webservice和RESTful Webservice
浅谈SOAP Webservice和RESTful Webservice REST是一种架构风格,其核心是面向资源,REST专门针对网络应用设计和开发方式,以降低开发的复杂性,提高系统的可伸缩性.RE ...
- 浅谈WebService SOAP、Restful、HTTP(post/get)请求
http://www.itnose.net/detail/6189456.html 浅谈WebService SOAP.Restful.HTTP(post/get)请求 2015-01-09 19:2 ...
- 浅谈ITIL
本节内容 浅谈ITIL CMDB介绍 Django自定义用户认证 Restful 规范 资产管理功能开发 浅谈ITIL TIL即IT基础架构库(Information Technology Infra ...
- 【http协议】浅谈
[http协议]浅谈 一. 概述 http,超文本传输协议(HyperText Transfer Protocol)是互联网上应用最为广泛的一种网络协议. 请求与响应: 客户端发送请求,服务器端响应数 ...
- 浅谈REST API
浅谈REST API 说明: 本文部分内容根据其它网络文章编写,如有版权问题请及时通知. 背景 发迹于互联网的REST,在国内国外混得可谓是风生水起,如今又进入电信行业的视野,连TMF都将其作为战略项 ...
- 微服务浅谈&服务治理的演变过程
这两天对互联网的架构演变进行了简单了解,并对微服务的出现很感兴趣,所以对相关知识进行了简单的整理与总结. 本篇文章先简单介绍了互联网架构的演变,进而介绍了服务化,最后介绍了微服务及最新的服务网格(Se ...
- 阿里P7浅谈SpringMVC
一.前言 既然是浅谈 SpringMVC,那么我们就先从基础说起,本章节主要讲解以下内容: 1.三层结构介绍 2.MVC 设计模式介绍 3.SpringMVC 介绍 4.入门程序的实现 注:介绍方面的 ...
- 转:浅谈HTTP中Get、Post、Put与Delete的区别
1.GET请求会向数据库发索取数据的请求,从而来获取信息,该请求就像数据库的select操作一样,只是用来查询一下数据,不会修改.增加数据,不会影响资源的内容,即该请求不会产生副作用.无论进行多少次操 ...
随机推荐
- 必备Linux命令和C语言基础
每一个学习嵌入式单片机的伙伴我相信对于这两个都不陌生,这毕竟是嵌入式单片机的生存之道 所有基础还是要打牢的 有句老话说的好基础不牢地动山摇 下面看下系统的资料吧 希望能对大家有所帮 ...
- linux CentOS 安装 nginx+tomcat+java+mysql运行环境
本文介绍了CentOS7 64 Java,Tomcat,MySQL,Maven热部署等服务器环境的搭建过程. 服务器: 已经将所需要的工具(Xshell,Xftp.FileZilla等sftp上传工具 ...
- v-for同时循环一个对象和数组
<!DOCTYPE html> <html lang="zh"> <head> <meta charset="UTF-8&quo ...
- CF1033G Chip Game
题意 给你一个长度为\(n\)的序列和一个数\(m\). 小A和小B分别在\([1,m]\)选出一个数\(a\)和\(b\),然后开始游戏. 轮到小A时,他选择一个元素减\(a\):小B则选择一个元素 ...
- Cross-Origin跨域问题
为什么会跨域,要先了解浏览器的同源策略SOP(Same Orign Policy) https://segmentfault.com/a/1190000015597029 同源: 如果两个页面的协议 ...
- android studio application应用打包jar
转载: https://blog.csdn.net/xiayiye5/article/details/79639044 首先我们来说下打成jar包的分类: 1.application应用打成jar包 ...
- Oracle SQL 部分特殊字符转义及escape的用法
在处理sql时,遇到insert 或update 的参数中含有特殊字符“&”,下划线“_”, 单引号" ' "等时,要做转义处理. 例:插入特殊字元'&' upda ...
- Oracle安装和配置Oracle数据库快速指南
Oracle安装12C要求参考文档 汇总 中文版:在 Unix AIX,HP-UX,Linux,Solaris 和 MS Windows 操作系统上安装和配置 Oracle 数据库(RDBMS)的要求 ...
- python中利用matplotlib绘图可视化知识归纳
python中利用matplotlib绘图可视化知识归纳: (1)matplotlib图标正常显示中文 import matplotlib.pyplot as plt plt.rcParams['fo ...
- 关于11G DataGuard 日志传输的案例
案例探讨 在归档和非归档模式下,配置参数log_archive_dest_2后,DG的备库是否传输日志. 案例环境描述 本次环境如下,一套RAC+单机DG,然后从DG还原出来一个单独的测试库A,测试库 ...