前往小程序,Get更优阅读体验!
立即前往
首页
学习
活动
专区
工具
TVP
发布
社区首页 >专栏 >聊聊rest api设计

聊聊rest api设计

作者头像
code4it
发布2018-09-17 16:45:42
9510
发布2018-09-17 16:45:42
举报
文章被收录于专栏:码匠的流水账

本文主要研究下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实现端到端的动态查询
本文参与 腾讯云自媒体同步曝光计划,分享自微信公众号。
原始发表:2018-05-20,如有侵权请联系 cloudcommunity@tencent.com 删除

本文分享自 码匠的流水账 微信公众号,前往查看

如有侵权,请联系 cloudcommunity@tencent.com 删除。

本文参与 腾讯云自媒体同步曝光计划  ,欢迎热爱写作的你一起参与!

评论
登录后参与评论
0 条评论
热度
最新
推荐阅读
目录
  • 设计准则
  • 输入规范
  • 输出规范
  • 安全相关
  • 服务质量保障
  • 小结
  • doc
相关产品与服务
验证码
腾讯云新一代行为验证码(Captcha),基于十道安全栅栏, 为网页、App、小程序开发者打造立体、全面的人机验证。最大程度保护注册登录、活动秒杀、点赞发帖、数据保护等各大场景下业务安全的同时,提供更精细化的用户体验。
领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档