10个有关RESTful API良好设计的最佳实践
Web API已经在最近几年变成重要的话题,一个干净的API设计对于后端系统是非常重要的。
通常我们为Web API使用RESTful设计,REST概念分离了API结构和逻辑资源,通过Http方法GET, DELETE, POST 和 PUT来操作资源。
下面是进行RESTful Web API十个最佳实践,能为你提供一个良好的API设计风格。
1.使用名词而不是动词
Resource |
GET 读 |
POST 创建 |
PUT 修改 |
PATCH 部分修改 |
DELETE |
/cars | 返回 cars集合 | 创建新的资源 | 批量更新cars | 批量更新cars部分内容 | 删除所有cars |
/cars/711 | 返回特定的car | 该方法不允许(405) | 更新一个指定的资源 | 更新指定资源的部分内容 | 擅长指定资源 |
不要使用:
/getAllCars
/createNewCar
/deleteAllRedCars
2.Get方法和查询参数不应该涉及状态改变
使用PUT, POST 和DELETE 方法 而不是 GET 方法来改变状态,不要使用GET 进行状态改变:
GET /users/711?activate
GET /users/711/activate
3.使用复数名词
不要混淆名词单数和复数,为了保持简单,只对所有资源使用复数。
/cars 而不是 /car
/users 而不是 /user
/products 而不是 /product
/settings 而部署 /setting
4. 使用子资源表达关系
如果一个资源与另外一个资源有关系,使用子资源:
GET /cars/711/drivers/ 返回 car 711的所有司机
GET /cars/711/drivers/4 返回 car 711的4号司机
5.使用Http头声明序列化格式
在客户端和服务端,双方都要知道通讯的格式,格式在HTTP-Header中指定
Content-Type 定义请求格式
Accept 定义系列可接受的响应格式
6.使用HATEOAS
Hypermedia as the Engine of Application State 超媒体作为应用状态的引擎,超文本链接可以建立更好的文本浏览:
{
"id": 711,
"manufacturer": "bmw",
"model": "X5",
"seats": 5,
"drivers": [
{
"id": "23",
"name": "Stefan Jauker",
"links": [
{
"rel": "self",
"href": "/api/v1/drivers/23"
}
]
}
]
}
注意href指向下一个URL
7.为集合提供过滤 排序 选择和分页等功能
Filtering过滤:
使用唯一的查询参数进行过滤:
GET /cars?color=red 返回红色的cars
GET /cars?seats<=2 返回小于两座位的cars集合
Sorting排序:
允许针对多个字段排序
GET /cars?sort=-manufactorer,+model
这是返回根据生产者降序和模型升序排列的car集合
Field selection
移动端能够显示其中一些字段,它们其实不需要一个资源的所有字段,给API消费者一个选择字段的能力,这会降低网络流量,提高API可用性。
GET /cars?fields=manufacturer,model,id,color
Paging分页
使用 limit 和offset.实现分页,缺省limit=20 和offset=0;
GET /cars?offset=10&limit=5
为了将总数发给客户端,使用订制的HTTP头: X-Total-Count.
链接到下一页或上一页可以在HTTP头的link规定,遵循Link规定:
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.
一般在Url后面使用?v
/blog/api/v1
9. 使用Http状态码处理错误
如果你的API没有错误处理是很难的,只是返回500和出错堆栈不一定有用
Http状态码提供70个出错,我们只要使用10个左右:
200 – OK – 一切正常
201 – OK – 新的资源已经成功创建
204 – OK – 资源已经成功擅长
304 – Not Modified – 客户端使用缓存数据
400 – Bad Request – 请求无效,需要附加细节解释如 "JSON无效"
401 – Unauthorized – 请求需要用户验证
403 – Forbidden – 服务器已经理解了请求,但是拒绝服务或这种请求的访问是不允许的。
404 – Not found – 没有发现该资源
422 – Unprocessable Entity – 只有服务器不能处理实体时使用,比如图像不能被格式化,或者重要字段丢失。
500 – Internal Server Error – API开发者应该避免这种错误。
使用详细的错误包装错误:
{
"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方法
一些代理只支持POST 和 GET方法, 为了使用这些有限方法支持RESTful API,需要一种办法覆盖http原来的方法。
使用订制的HTTP头 X-HTTP-Method-Override 来覆盖POST 方法.
转自:http://www.jdon.com/soa/10-best-practices-for-better-restful-api.html
10个有关RESTful API良好设计的最佳实践相关推荐
- RESTful API的设计原则
说在前面,这篇文章是无意中发现的,因为感觉写的很好,所以翻译了一下.由于英文水平有限,难免有出错的地方,请看官理解一下.翻译和校正文章花了我大约2周的业余时间,如有人愿意转载请注明出处,谢谢^_^ P ...
- Eggjs笔记:RESTful API的设计
关于RESTful API 网络应用程序,分为前端和后端两个部分.当前的发展趋势,就是前端设备层出不穷(手机.平板.桌面电脑.其他专用设备-). 因此,必须有一种统一的机制,方便不同的前端设备与后端进 ...
- 架构必备「RESTful API」设计技巧经验总结
转载自 架构必备「RESTful API」设计技巧经验总结 [译者注]本文是作者在自己的工作经验中总结出来的RESTful API设计技巧,虽然部分技巧仍有争议,但总体来说还是有一定的参考价值的. ...
- mysql数据库设计实践_MYSQL教程分享20个数据库设计的最佳实践
<MYSQL教程分享20个数据库设计的最佳实践>要点: 本文介绍了MYSQL教程分享20个数据库设计的最佳实践,希望对您有用.如果有疑问,可以联系我们. MYSQL教程数据库设计是整个程序 ...
- Prometheus Metrics 设计的最佳实践和应用实例,看这篇够了!
Prometheus 是一个开源的监控解决方案,部署简单易使用,难点在于如何设计符合特定需求的 Metrics 去全面高效地反映系统实时状态,以助力故障问题的发现与定位.本文即基于最佳实践的 Metr ...
- 卡片式设计的最佳实践分享
2017-02-17 三达不留点gpj CocoaChina 卡片本质上是一个简单的信息容器,信息量有限,但设计干净整洁.现如今,在保证界面具有优秀可用性的同时,卡片式的设计甚至成为了平衡界面美学的默 ...
- 搜索引擎优化网页设计:最佳实践
作为一名网页设计师.网页的设计是我们一个最直观的辨认.我们如今的生活依赖于网络,依赖于这个高速让我们互知和沟通的工 具.它早已不不过一个静态的页面,而是一个有思想有文化无国界的一个内容涵盖量丰富的还有 ...
- 好RESTful API的设计原则
做出一个好的API设计很难.API表达的是你的数据和你的数据使用者之间的契约.打破这个契约将会招致很多愤怒的邮件,和一大堆伤心的用户-因为他们手机上的App不工作了.而文档化只能达到一半的效果,并且也 ...
- Restful API的设计思路
API的就是程序员的UI,和其他UI一样,你必须仔细考虑它的用户体验! Restful只是web api/Json传输接口通过http调,取到还要自己解.Rpc一般都是配套的,客户端直接像调本地函数一 ...
最新文章
- Vector源码分析
- man mysql_几个容易被忽略的mysql知识
- CF 1635E Cars 二分图 + 拓扑
- HTML代码转换编辑器
- UE4中FString转UTF8及UTF8转FString
- 堆密度测定的意义_堆积密度的测量有何意义汇美科LABULK0335
- 2021年计算机保研面试题
- 佳能计算机使用方法,佳能扫描仪怎么用?佳能扫描仪使用方法
- MATLAB将xyz数据转换成STL文件
- el-input 只能输入整数(包括正数、负数、0)或者只能输入整数(包括正数、负数、0)和小数
- 阐述免费增值游戏的设计特点及注意事项
- nginx配置禁止访问目录或禁止访问目录下的文件
- Excel表格中如何快速在空白处添加短横杠(-)
- nose 测试框架使用
- 旋转电机设计_尤哈·皮罗内 PDF完整版下载 网盘分享
- 误删分区怎么办?必备数据恢复工具!
- linux桌面无法显示U盘,电脑桌面右下角不能显示u盘图标解决方法
- 设计电子计算机,电机设计电子计算机在电机设计计算中的应用(电机设计CAD)...
- 全球疫情可视化实时更新
- 【中小学科技竞赛】哪些比赛较有含金量值得参加?如何获取赛事信息?
热门文章
- 关于mysql_free_result和mysql_close的解惑
- (一) 双目立体视觉介绍
- 百度地图标点点击变色_原神wiki地图工具,原神全地图资源标记全览
- java的robot_Java中的Robot不执行命令
- Java应用案例分析_Java应用启动参数实例解析
- Linux 查询股价工具,find 查找工具
- java的字符串复制_我应该如何复制Java中的字符串?
- 井通swtc能不能涨到2元_玉米收购价最高涨110元一吨,节后玉米能否破1.2?收购商说得有理...
- 电脑开机一会就蓝屏怎么回事_电脑使用过程中会蓝屏,老板三分钟做系统:硬盘坏了,四百换好!...
- 拼接播放地址_西安户外did拼接屏批发业务广泛_金伟达电子