RESTful API的十个最佳实践
WebAPI在过去几年里非常的盛行,我们很多以往的技术手段都慢慢的转换为使用WebAPI来开发,因为它的语法简单规范化,以及轻量级等特点,这种方式收到了广泛的推崇。
通常我们使用RESTFul(Representational State Transfer)的设计方式来设计Web api,这通常用来分离API结构了业务逻辑,它使用典型的HTTP方法,诸如GET,POST.DELETE,PUT来和资源进行交互。
以下是设计RESTful API的是个最佳实践:
1. 使用名词而不是动词
为了易于理解,为资源使用下面的API结构:
Resource | Get read |
Post create |
Put update |
Delete |
/cars | 返回一个car的列表 | 创建一个新的car | 更新car的信息 | 删除所有的car |
/cars/2 | 返回指定的car | Method not allowed(405) | 更新指定的car的信息 | 删除指定的car |
不要使用动词
/getAllCars
/createNewCar
/deleteAllRedCars
2. Get方法和查询参数不应该改变资源状态
使用Put,Post和Delete方法替代Get方法来改变资源状态。不要使用Get来使状态改变:
GET /users/711?activate or
GET /users/711/activate
3. 使用名词的复数形式
不要混合使用单数和复数形式,而应该为所有资源一直保持使用复数形式:
/cars instead of /car
/users instead of /user
/products instead of /product
/settings instead of /setting
4. 为关系使用子资源
假如资源连接到其它资源,则使用子资源形式:
GET /cars/711/drivers/ Returns a list of drivers for car 711
GET /cars/711/drivers/4 Returns driver #4 for car 711
5. 使用HTTP头决定序列化格式
在客户端和服务端都需要知道使用什么格式来进行通信,这个格式应该在HTTP头中指定:
- Content-Type:定义请求的格式;
- Accept :定义允许的响应格式的列表
6. 使用HATEOAS
Hypermedia as the Engine of Application State是一个指导原则,它规定超文本链接应该被用于在API中创建更好的资源导航:
{
"id": 711,
"manufacturer": "bmw",
"model": "X5",
"seats": 5,
"drivers": [
{
"id": "23",
"name": "Stefan Jauker",
"links": [
{
"rel": "self",
"href": "/api/v1/drivers/23"
}
]
}
]
}
7. 为集合提供过滤、排序、字段选择以及分页
过滤
为所有字段或者查询语句提供独立的查询参数:
GET /cars?color=red Returns a list of red cars
GET /cars?seats<=2 Returns a list of cars with a maximum of 2 seats
排序
允许跨越多字段的正序或者倒序排列:
GET /cars?sort=-manufactorer,+model
字段选择
一些情况下,我们只需要在列表中查询几个有标识意义的字段,我们不需要从服务端把所有字段的值都请求出来,所以需要支持API选择查询字段的能力,这也可以提到网络传输性能和速度:
GET /cars?fields=manufacturer,model,id,color
分页
使用offset和limit来获取固定数量的资源结果,当其中一个参数没有出现时,应该提供各自的默认值,比如默认取第一页,或者默认取20条数据:
GET /cars?offset=10&limit=5
GET /cars?&limit=5 //Get first five result
GET /cars?&offset=5 //Get default amount result offset 5
使用自定义的头X-Total-Count发回给调用段实际的资源数量。
前一页后一页的链接也应该在HTTP头链接中得到支持,遵从下文中的链接原则而不要构建你自己的头:
Link: <https://blog.mwaysolutions.com/sample/api/v1/cars?offset=15&limit=5>; rel="next",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=50&limit=3>; rel="last",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=0&limit=5>; rel="first",
<https://blog.mwaysolutions.com/sample/api/v1/cars?offset=5&limit=5>; rel="prev",
8. 版本化你的API
确保强制实行API版本,并且不要发布一个没有版本的API,使用简单的序列数字,避免使用2.5.0这样的形式:
/blog/api/v1
9. 使用HTTP状态码处理错误
忽略错误处理的API是很难使用的,简单的返回500和调用堆栈是非常不友好也非常无用的:
使用HTTP状态码
HTTP标准提供了70多个状态码来描述返回值,我们不需要完全用到他们,下文中列出10个使用率较高的:
200 – OK – 一切正常
201 – OK – 新资源已经被创建
204 – OK – 资源删除成功
304 – 没有变化,客户端可以使用缓存数据
400 – Bad Request – 调用不合法,确切的错误应该在error payload中描述,例如:“JSON 不合法 ”
401 – 未认证,调用需要用户通过认证
403 – 不允许的,服务端正常解析和请求,但是调用被回绝或者不被允许
404 – 未找到,指定的资源不存在
422 – 不可指定的请求体 – 只有服务器不能处理实体时使用,比如图像不能被格式化,或者重要字段丢失。
500 – Internal Server Error – 标准服务端错误,API开发人员应该尽量避开这种错误
使用 error payloads
所有的异常都应该被映射到error payloads中,下文中的例子是一个json payload的模板:
{
"errors": [
{
"userMessage": "Sorry, the requested resource does not exist",
"internalMessage": "No car found in the database",
"code": 34,
"more info": "http://dev.mwaysolutions.com/blog/api/v1/errors/12345"
}
]
}
10. 允许重写HTTP方法
一些代理只支持GET和POST方法,为了在这种限制下支持RESTful API,API需要重写HTTP方法。
使用自定义的X-HTTP-Method-Override HTTP头来重写POST方法。
RESTful API的十个最佳实践的更多相关文章
- atitit.基于http json api 接口设计 最佳实践 总结o7
atitit.基于http json api 接口设计 最佳实践 总结o7 1. 需求:::服务器and android 端接口通讯 2 2. 接口开发的要点 2 2.1. 普通参数 meth,p ...
- RESTful接口设计原则/最佳实践(学习笔记)
RESTful接口设计原则/最佳实践(学习笔记) 原文地址:http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api 1 ...
- [翻译] API测试的最佳实践 - 介绍
API测试的最佳实践 - 介绍 在上一篇“是什么让API测试很叼”一文中,我们讨论API与其他形式的软件测试的差异.部分是因为API之间的通信压根就没考虑让你能读懂,纯粹是为了方便计算机之间的交互而设 ...
- 理解RESTful:理论与最佳实践
什么是 REST 什么是 RESTful Richardson 成熟度模型 RESTful API 设计最佳实践 补充:HTTP 状态码及说明 什么是 REST REST 一词,是由 HTTP 协议的 ...
- 【转】Java中关于异常处理的十个最佳实践
原文地址:http://www.searchsoa.com.cn/showcontent_71960.htm 导读:异常处理是书写强健Java应用的一个重要部分,Java许你创建新的异常,并通过使用 ...
- Restful API的设计与实践
Restful这个名称应该很多人都不陌生,但是我发现不少人对Restful存在或多或少的理解偏差,其中不泛比较厉害的程序员,所以有必要为Restful来“正名”. Restful是一种软件架构风格,设 ...
- Hadoop管理员的十个最佳实践
前言 接触Hadoop有两年的时间了,期间遇到很多的问题,既有经典的NameNode和JobTracker内存溢出故障,也有HDFS存储小文件问题,既有任务调度问题,也有MapReduce性能问题.遇 ...
- Hadoop管理员的十个最佳实践(转)
前言 接触Hadoop有两年的时间了,期间遇到很多的问题,既有经典的NameNode和JobTracker内存溢出故障,也有HDFS存储小文件问题,既有任务调度问题,也有MapReduce性能问题.遇 ...
- [转] Hadoop管理员的十个最佳实践
前言 接触Hadoop有两年的时间了,期间遇到很多的问题,既有经典的NameNode和JobTracker内存溢出故障,也有HDFS存储小文件问题,既有任务调度问题,也有MapReduce性能问题.遇 ...
随机推荐
- Springboot+ajax传输json数组以及单条数据的方法
Springboot+ajax传输json数组以及单条数据的方法 下面是用ajax传输到后台单条以及多条数据的解析的Demo: 结构图如下: 下面是相关的代码: pom.xml: <?xml v ...
- 四则运算2及psp0设计
随机生成运算式,要求: 1.题目避免重复. 2.可定制(数量/打印方式). 3.可以控制一下参数. 要求:是否有乘除法,是否有括号,数值范围,加减有无负数,除法有无余数. 刚开始看到这样一个题目感觉还 ...
- 软件魔方制作系统启动盘并安装win7系统
不多说,直接上干货! 推荐软件:软件魔方 http://mofang.ruanmei.com/ 这里,我想说的是,这个软件来制作系统盘,是真的方便和好处多多.具体我不多说,本人也是用过其他的如大白菜等 ...
- Javac语法糖之其它
1.变长参数 class VarialbeArgumentsDemo { public static void doWork(int... a) {//可变参数 } public static voi ...
- OpenGL11-绘制汉字最高效方法(使用Freetype)(代码已更新)
最新版本,之前的版本有些文件没有打包 视频教程请关注 http://edu.csdn.net/lecturer/lecturer_detail?lecturer_id=440 OpenGL本身并没有绘 ...
- protocol buffers生成go代码原理
本文描述了protocol buffers使用.proto文件生成pb.go文件的过程 编译器 编译器需要插件来编译环境,使用如下方式安装插件:go get github.com/golang/pro ...
- nginx配置负载均衡,tomcat宕机响应缓慢,自动切换的问题
用了nginx负载均衡后,在两台tomcat正常运行的情况下,访问http://localhost 速度非常迅速,通过测试程序也可以看出是得到的负载均衡的效果,但是我们试验性的把其中一台tomcat( ...
- Linux 搭建Hadoop集群错误锦集
一.Hadoop集群配置好后,执行start-dfs.sh后报错,一堆permission denied zf sbin $ ./start-dfs.sh Starting namenodes on ...
- 04-python的列表操作
python中列表的使用最多, 常用的方法有: append(value) extend(L) 添加指定列表的所有元素 insert(index, value) 插入 remove(value) po ...
- java面试⑥框架部分
2.5.1 什么是框架: 2.5.2 MVC模式 2.5.3 MVC框架 2.5.4 简单讲一下struts2的执行流程 2.5.5 Struts2中的拦截器,你都用它干什么? 2.5.6 简单讲一下 ...