聊聊rest api设计

本文主要研究下rest api的设计。

设计准则

  • easy to use & hard to misuse 易用不易误用,也就是api设计不要太复杂,要简单易用,而且还不能容易用错。
  • least astonishment 简单就好,不要试图提供其他花哨、华丽的额外功能,比如对于时间类似的字符串参数,规定好一个输入格式即可,不要试图同时兼容多种格式输入。
  • use case & document story api文档要围绕story或者use case来进行,在一个业务场景下提供完整的闭环操作。

输入规范

  • url中的参数避免驼峰,避免下划线,优先采用横杠
  • 分页比如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实现端到端的动态查询

原文发布于微信公众号 - 码匠的流水账(geek_luandun)

原文发表时间:2018-05-20

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

发表于

我来说两句

0 条评论
登录 后参与评论

相关文章

来自专栏鸿的学习笔记

协程--以Python和Go为例

一条线程指的是进程中一个单一顺序的控制流,一个进程中可以并发多个线程,每条线程并行执行不同的任务。

31510
来自专栏玄魂工作室

Hacker基础之工具篇 APT2

所有模块结果都存储在本地主机上,并且是APT2知识库(Knowledge Base)的一部分

12730
来自专栏尚国

深入剖析最新IE0day漏洞

在2018年4月下旬,我们使用沙箱发现了IE0day漏洞;自从在野外发现上一个样本(CVE-2016-0189)已经有两年多了。从许多方面来看,这个特别的漏洞及...

15820
来自专栏我的博客

学会编程更要学会找错误

一直想写点我在编程学习中遇到的问题以及我是如何解决的,我是一个PHPer,而且对计算机有着深厚的兴趣。今天闲着没事,就顺手整理一点,随后会相继会做更多总结,敬请...

41070
来自专栏Android-JessYan

一行代码实现Okhttp,Retrofit,Glide下载上传进度监听

原文地址: http://www.jianshu.com/p/5832c776621f qq群:301733278

21320
来自专栏Ken的杂谈

屏蔽浏览器对网页JS脚本错误提示

网页脚本基本已经成了现在网站开发中不可或缺的元素,无论是使用JS:Javascript还是使用其他JS库:

30210
来自专栏黑泽君的专栏

JavaScript的介绍

 javascript是什么?     javascript 是因特网上最流行的脚本语言,它存在于全世界所有 Web 浏览器中,能够增强用户与 Web 站...

8820
来自专栏程序员的知识天地

Python代码注释的一些基础知识

在编写Python代码时,确保您的代码易于被其他人理解是很重要的。给变量、函数起合适的名字以及合理地组织代码都是很好的方法。

22760
来自专栏blackheart的专栏

如何站在使用者的角度来设计SDK-微信公众号开发SDK(消息处理)设计之抛砖引玉

0.SDK之必备的基本素质 在项目中免不了要用到各种各样的第三方的sdk,在我现在的工作中就在公司内部积累了各种各样的的公共库(基于.net的,基于silver...

26590
来自专栏逸鹏说道

c# 温故而知新: 线程篇(一) 上

Thread 目录: 目录: 1 线程基础的简单介绍 2 线程同步与线程异步的简单介绍 3 前台线程与后台线程的简单介绍 4 细说下Thread 最为关键的构造...

27380

扫码关注云+社区

领取腾讯云代金券