[case20]聊聊rest api设计
序
本文主要研究下rest api的设计。
设计准则
- easy to use & hard to misuse
易用不易误用,也就是api设计不要太复杂,要简单易用,而且还不能容易用错。
- least astonishment
简单就好,不要试图提供其他花哨、华丽的额外功能,比如对于时间类似的字符串参数,规定好一个输入格式即可,不要试图同时兼容多种格式输入。
- use case & document story
api文档要围绕story或者use case来进行,在一个业务场景下提供完整的闭环操作。
输入规范
- url中的路径
避免驼峰,避免下划线,优先采用横杠
- request method
post表示新增(
url中没有id
),delete表示删除,get表示查询,put表示全量更新(幂等操作
),post url中携带id也可用于表示更新。
- 分页
比如page及size,或者limit及offset
- 排序
比如sort=+field2,-field2,用逗号分隔多个排序字段,用+表示升序,用-表示降序
- 字段过滤
比如fields=field1,field2,field3
- 复杂查询
简单的比如用eq代表等,lt代表小于,lte代表小于等于,gt代表大于,gte代表大于等于,like代表模糊查询;更复杂的话,可以参考rsql规范。
- 版本
不建议版本化,建议采用新的领域命名才与原有的api区分开来
输出规范
- 返回码
遵循http的返回码规范,4xx表示客户端错误,5xx表示服务端错误。
- 返回jsonObject而不是jsonArray
顶层结构返回jsonArray的话,就不容易扩展了。一般返回jsonObject,通常会携带code,error之类的
- 返回jsonObject的字段
success表示请求是否成功,data表示数据,msg表示消息描述,error描述错误信息详情。
- 错误信息格式
type表示错误异常类型,code表示错误编号用于个性化错误提示,msg用于错误信息描述,link提供该错误信息的具体描述页面
安全相关
- 调用方鉴权
对于api的消费者,要求调用的时候强制提供appId及appKey,用于最基本的调用源的鉴权
- 细粒度鉴权
对于更细粒度的数据权限控制,要细化到url及requestMethod基本
- 参数校验
对于查询、修改等参数要做基本校验,对参数内容进行非法参数过滤。
- 屏蔽错误堆栈
不要暴露后端的错误堆栈,如果是要方便排查问题,可以设置一个开关,来设置是否屏蔽错误堆栈
- 敏感数据脱敏
对于敏感的数据,要适当做一些脱敏处理,比如身份证号,手机号等。在真正需要真实数据的话,需要额外进行请求。
- 账号密码需要加密
登陆接口必须走https,而且必须要有图形验证码,而且还必须防暴力破解,有错误锁定机制,对于密码的传递,必须加密处理
- 防止id遍历问题
对于url的参数,如果id是递增的,则需要处理遍历问题,要么对外暴露经过处理后的id,要么做数据权限控制
- 防止token replay
对于token要有一定的失效机制,另外建议token对url参数进行签名
- 防止文件下载目录遍历
对于提供文件下载的接口,一定要避免目录遍历问题
服务质量保障
- 提供SLA
- 提供流量管理、熔断、限流
- 提供服务扩容机制
- 提供故障演练
- 提供审计功能
- 监控异常流量
- 提供调用方间的隔离
小结
rest api的设计牵扯的方面比较多,本文暂时只是先列了一些,后续有待补充。
doc
- API设计要点
- 聊聊jpa的动态查询
- 使用RSQL实现端到端的动态查询
[case20]聊聊rest api设计相关推荐
- 我是如何根据豆瓣api来理解Restful API设计的
1.什么是REST REST全称是Representational State Transfer,表述状态转移的意思.它是在Roy Fielding博士论文首次提出.REST本身没有创造新的技术.组件 ...
- RESTful API 设计最佳实践
2019独角兽企业重金招聘Python工程师标准>>> 背景 目前互联网上充斥着大量的关于RESTful API(为方便,下文中"RESTful API "简写为 ...
- java api 设计_Java API设计实践
使你的API在模块化和非模块化Java环境中都可用 在优锐课的java学习分享中,对微服务有了更深层次的新概念.关于API设计实践一点就通了. 介绍 了解设计Java API时应应用的一些API设计实 ...
- 22条API设计的最佳实践
译者:刘志超,软件工程师.DevOpsDays.HDZ深圳核心组织者,目前供职于华为,从事云计算工作,专注于K8s.微服务领域. 来源:dockone.io/article/2434604 原文:ht ...
- RESTful架构和RESTful API设计总结
作者:智明书 链接:https://www.jianshu.com/p/955eb2faa354 REST这个词是2000年Roy Fielding在他的博士论文中提出的,Fielding参与了htt ...
- java 最小化 api_Java的API设计实践
Introduction 了解在设计Java API时应该应用的一些API设计实践.通常,这些实践很有用,并确保API可以在模块化环境中正确使用,例如OSGi和Java平台模块系统(JPMS).有些做 ...
- 独家 | 提升API设计技能的22个最佳实践(附链接)
作者:Mohammad Faisal翻译:张一然校对:和中华本文约2000字,建议阅读7分钟本文介绍了有关设计REST api的一些实用建议. 你是否曾对处处都像猜谜游戏一样的糟糕API感到生气, 好 ...
- Google API 设计指南-设计模式
翻译自 API Design Guide - Design Patterns 空响应体 标准的 Delete 方法 必须(must) 返回 google.protobuf.Empty 来实现全局一致性 ...
- java开发checklist,Java API设计CheckList
API设计原则:正确.好名.易用.易学.够快.够小.但我们从来不缺原则,〜〜〜 Interface 1.The Importance of Being Use Case Oriented,一个接口应当 ...
最新文章
- 笔记-项目管理基础知识-复习要点
- python settings模块安装_Python settings-helper包_程序模块 - PyPI - Python中文网
- 函数式接口@FunctionalInterface使用示例
- 打造一个属于自己的应用服务自动监控警报程序
- Codeforces Round #586 (Div. 1 + Div. 2) B. Multiplication Table 思维 + 公式
- python两列数据生成邻接矩阵_用python实现邻接矩阵转换为邻接表,python语言实现...
- java获取已经打开的串口的输出流_使用Java读取串口的程序(转)
- mysql group by cube_SQL Server 之 GROUP BY、GROUPING SETS、ROLLUP、CUBE
- Mysql学习总结(57)——MySQL查询当天、本周、本月、上周、本周、上月、距离当前现在6个月数据
- python中元组和列表的区别_Python 序列:列表、元组
- iOS启动动画效果实现
- Android 多媒体框架stagefright
- php 架构师之路ioc讲解
- 三国志战略版:四大阵营武将总结——魏国篇
- 机器视觉打光方式相关问题汇总
- elementUI中el-table每行异常高度原因排查,累死
- 推荐3个Windows电脑上的epub小说阅读器
- Soapui报错There are currently 1 running SoapUI MockServices解决办法
- Selenium学习_常用场景代码示例
- SCT2430STER电池应用
热门文章
- solr kerberos java_solr添加kerberos认证及授权
- padavan支持惠普打印服务器,[分享]Padavan打印机共享,电脑和手机上添加,亲测通过!...
- android短信发送乱码,解决CEMAPI发送中文短信时会乱码
- 基于英飞凌AURIX的平衡单车组逐飞BLDC项目开源
- 第十六届全国大学生智能汽车竞赛总决赛 AI视觉组线上赛细则
- 2021年春季学期-信号与系统-第十二次作业参考答案-第一小题
- 2021年春季学期-信号与系统-第一次作业参考答案-第六题
- 使用TESSERACT来识别字符
- 2020人工神经网络第一次作业-解答第一部分
- mybatis巨坑:if标签判断如果类型是integer,值为0,判断不成立(传入0值使用MyBatis查询不生效的原因)