RESTful API 简书
RESTful API
概述
RESTful架构是一种流行的互联网软件架构,它结构清晰,符合标准,易于理解,扩展方便。
REST是Representational State Transfer的缩写,翻译为“表现层状态转化”。表现层其实就是资源,因此可以理解为“资源状态转化”。
网络应用上的任何实体都可以看作是一种资源,通过一个URI(统一资源定位符)指向它。
表现层(Representation)
“资源”是一种信息实体,它可以有多种外在表现形式。我们把“资源”具体呈现出来的形式叫做它的“表现层”。
例如,文本可以是txt格式表现,也可以用HTML格式,XML格式,JSON格式表现;图片可以是JPG格式也可以是PNG格式表现等。
URI之代表资源实体,不代表它的形式。URI应该之代表“资源”的位置,而它具体的表现形式应该在HTTP请求的头信息中用Accept和Content-Type字段指定,这两个字段才是对“表现层”的描述。
状态转化(State Transfer)
访问一个WEB应用就代表了客户端与服务短的一个互动过程。HTTP协议是一个无状态协议。因此所有的状态都保存在服务端。如果客户端想要操作服务器,就必须通过某种手段让服务端发生“状态变化”(State Transfer)。而这种状化是建立在表现层之上的,所以就是“表现层状态转化”。
总结什么是RESTful架构
- 每一个URI代表一种资源
- 客户端和服务端之间传递这种资源的某种表现层
- 客户端通过HTTP动词(GET,POST,PUT,DELETE)对服务端资源进行操作,实现表现层状态转换
典型的设计误区
- URI包含动词。“资源”是一种实体,应该是名词。URI不应该有动词,动词放在HTTP协议中。
URI中加入版本号。例如
http://www.example.com/app/1.0/foo
http://www.example.com/app/1.1/foo
http://www.example.com/app/2.0/foo不同的版本可以理解为同一种资源的不同表现形式,所以应该用同一个URI,版本号可以在HTTP请求头信息中的Accept字段中区分:
Accept: vnd.example-com.foo+json; version=1.0
Accept: vnd.example-com.foo+json; version=1.1
Accept: vnd.example-com.foo+json; version=2.0
设计指南
协议
API与用户的通信协议,总是使用HTTPs协议
域名
应该尽量将API部署在专用域名之下。
如果确定API很简单,不会用进一步扩展,则可以考虑放在主域名下
版本
应该将API的版本号放入URI
也可以放在HTTP头信息中,但不如仿如URI直观
路径
路径就是API的网址,每一个路径代表一种资源,所以路径只有名词不能有动词。而且所用的名词往往与数据库表名对应。一般而言,数据库中的表是记录的集合,因此API中的名词也应该使用复数。例如:
https://api.example.com/v1/zoos
https://api.example.com/v1/animals
HTTP动词
对于资源的具体操作,由HTTP动词表示
常用的HTTP动词包括一下几个,括号里是对应的SQL命令:
- GET(SELECT): 从服务器取出资源(一个或多个)
- POST(CREATE): 在服务器新建一个资源
- PUT(UPDATE): 在服务器更新资源(客户端提供改变后的完整资源,即更新整一个资源)
- PATCH(UPDATE): 在服务器更新资源(客户端提供改变的属性,即更新资源的部分属性)
- DELETE(DELETE): 从服务器删除资源
还有两个不常用的HTTP动词
- HEAD: 获取资源的元数据
- OPTIONS: 获取信息,关于资源的哪些属性是客户端可以改变的
下面是若干例子:
- GET /zoos:列出所有动物园
- POST /zoos:新建一个动物园
- GET /zoos/ID:获取某个指定动物园的信息
- PUT /zoos/ID:更新某个指定动物园的信息(提供该动物园的全部信息)
- PATCH /zoos/ID:更新某个指定动物园的信息(提供该动物园的部分信息)
- DELETE /zoos/ID:删除某个动物园
- GET /zoos/ID/animals:列出某个指定动物园的所有动物
- DELETE /zoos/ID/animals/ID:删除某个指定动物园的指定动物
过滤信息(Filtering)
如果记录数过多,服务器不可能一次性将所有的信息返回给客户端。API应该提供参数,过滤返回结果。下面一些常见的参数:
- ?limit=10:指定返回记录的数量
- ?offset=10:指定返回记录的开始位置
- ?sortby=name&order=asc:指定返回结果按照哪个属性排序,以及排序顺序
- ?animal_type_id=1:指定筛选条件
参数的设计允许存在冗余,即允许API路径和URL参数偶尔有重复。比如,GET /zoo/ID/animals 与 GET /animals?zoo_id=ID 的含义是相同的。
状态码(Status Codes)
服务器向用户返回的状态码和提示信息,常见的有以下一些(方括号中是该状态码对应的HTTP动词)
- 200 OK - [GET]:服务器成功返回用户请求的数据,该操作是幂等的(Idempotent)
- 201 CREATED - [POST/PUT/PATCH]:用户新建或修改数据成功
- 204 NO CONTENT - [DELETE]:用户删除数据成功
- 400 INVALID REQUEST - [POST/PUT/PATCH]:用户发出的请求有错误,服务器没有进行新建或修改数据的操作,该操作是幂等的
- 404 NOT FOUND - [*]:用户发出的请求针对的是不存在的记录,服务器没有进行操作,该操作是幂等的
- 500 INTERNAL SERVER ERROR - [*]:服务器发生错误,用户将无法判断发出的请求是否成功
状态码的完整列表参见这里
错误处理
如果状态码是4XX,就应该向客户端返回出错信息。一般来说,返回的信息中将error作为键名。
{ error: "Invalid API key" }
返回结果
针对不同的操作,服务器想客户端返回的结果应该符合一下规范
- GET /collection:返回资源对象的列表(数组)
- GET /collection/resource:返回单个资源对象
- POST /collection:返回新生成的资源对象
- PUT /collection/resource:返回更新后完整的资源对象
- PATCH /collection/resource:返回更新后完整的资源对象
- DELETE /collection/resource:返回一个空文档
Hypermedia API
RESTful API最好做到Hypermedia,即返回结果中提供链接,指向其他API方法,是的用户不查文档,也知道该怎么做。比如,当用户向api.example.com的根目录发出请求,会得到这样一个文档:
{"link": {
"rel": "collection https://www.example.com/zoos",
"href": "https://api.example.com/zoos",
"title": "List of zoos",
"type": "application/vnd.yourformat+json"
}}
上面代码表示,文档中有一个link属性,用户读取这个属性就知道下一步该调用什么API了。rel表示这个API与当前网址的关系(collection关系,并给出该collection的网址),href表示API的路径,title表示API的标题,type表示返回类型
Hypermedia API的设计被称为HATEOAS。Github的API就是这种设计,访问api.github.com会得到一个所有可用API的网址列表
{
"current_user_url": "https://api.github.com/user",
"authorizations_url": "https://api.github.com/authorizations",
// ...
}
其他
- API的身份认证应该使用OAuth2.0框架
- 服务器返回的数据格式,应该尽量适应JSON,避免使用XML
RESTful API 简书的更多相关文章
- Laravel(PHP)使用Swagger生成API文档不完全指南 - 基本概念和环境搭建 - 简书
在PHPer中,很多人听说过Swagger,部分人知道Swagger是用来做API文档的,然而只有少数人真正知道怎么正确使用Swagger,因为PHP界和Swagger相关的资料实在是太少了.所以鄙人 ...
- 虚拟研讨会:如何设计好的RESTful API?
http://www.infoq.com/cn/articles/how-to-design-a-good-restful-api/ REST架构风格最初由Roy T. Fielding(HTTP/1 ...
- 虚拟研讨会:如何设计好的RESTful API(转)
原文:虚拟研讨会:如何设计好的RESTful API? REST架构风格最初由Roy T. Fielding(HTTP/1.1协议专家组负责人)在其2000年的博士学位论文中提出.HTTP就是该架构风 ...
- 4- vue django restful framework 打造生鲜超市 -restful api 与前端源码介绍
4- vue django restful framework 打造生鲜超市 -restful api 与前端源码介绍 天涯明月笙 关注 2018.02.20 19:23* 字数 762 阅读 135 ...
- 通过一组RESTful API暴露CQRS系统功能
命令和查询责任分离(CQRS)是由Greg Young提出的一种将系统的读(查询).写(命令)操作分离为两种独立子系统的架构模式.命令通常是异步执行的,并存储在一个事务型数据库中,而读操作则通常是最终 ...
- openlayers 3 简书
1. 简书http://www.jianshu.com/p/6785e755fa0d 2. 文档 http://anzhihun.coding.me/ol3-primer/ch03/03-02.htm ...
- Yii2框架RESTful API教程(一) - 快速入门
前不久做一个项目,是用Yii2框架写一套RESTful风格的API,就去查了下<Yii 2.0 权威指南 >,发现上面写得比较简略.所以就在这里写一篇教程贴,希望帮助刚接触Yii2框架RE ...
- iOS开发--Bison详解连连支付集成简书
"最近由于公司项目需要集成连连支付,文档写的不是很清楚,遇到了一些坑,因此记录一下,希望能帮到有需要的人." 前面简单的集成没有遇到什么坑,在此整理一下官方的集成文档,具体步骤如下 ...
- 仿简书分享:UIActivityViewController系统原生分享
接下来介绍UIActivityViewController: 1. 创建要分享的数据内容,加在一个数组 ActivityItems里. NSString *textToShare = @"我 ...
随机推荐
- 无法远程访问虚拟机中的EM (Oracle Enterprise Manager)
今天安装EM,因为文件系统采用ASM来控制,后面需要输入一些ASM相关的信息.这个ASMSNMP用户是新建,所以设个密码自己记下就行. Enter the following information: ...
- Asp.net 执行回调操作后 无法更新ViewState的问题
源码 待续...
- c# ref关键字对于引用类型传递的影响
我们可能见到下面的代码 public static void StringBuilderNoRef(StringBuilder s) { s.Append(" World" ...
- centos 主从复制
1.主服务器rpm安装mysql 2.复制一台服务器叫slave(从服务器),一会儿要用 3.在主服务器,修改my.cnf文件 找到server-id,在它的下面加上 binlog-do-db = h ...
- php5.2.6+apache2.2.15配置
首先下载软件,忘记php下载地址了,apache是官网. 文件名 httpd-2.2.15-win32-x86-openssl-0.9.8m-r2.msi php-5.2.6-win32-instal ...
- IOS中货币高精度要求使用NSDecialNumber、
float a = 0.01; int b =99999999; double c = 0.0; c = a * b; //如果单纯的使用double会导致数 ...
- 黑马程序员——JAVA基础之程序控制流结构之判断结构,选择结构
------- android培训.java培训.期待与您交流! ---------- 程序控制流结构:顺序结构:判断结构:选择结构:循环结构. 判断结构:条件表达式无论写成什么样子,只看最终的结构是 ...
- jQuery在IE浏览器上的html()报错 return !noData || noData !== true && elem.getAttribute("classid") === noData;
解决方法是,将Query 1.10.2版本的源码中的3791行: return !noData || noData !== true && elem.getAttribute(&quo ...
- OpenJudge计算概论-找最大数序列
/*===================================== 找最大数序列 总时间限制: 1000ms 内存限制: 65536kB 描述 输入n行(n 不大于 30),每行不超过10 ...
- Amazon后台登陆以及跟卖
亚马逊模拟登陆,这里使用的是selenium来登陆,并判断是否登陆成功,以及是否有验证码,并破解验证码登陆. 跟卖主要解决的难题是selenium的新窗口弹出问题,在 # 点击“出售您的” brows ...