API 接口设计规范

更新日期: 2020-01-25阅读: 2.3k标签: api

概述

这篇文章分享 api 接口设计规范,目的是提供给研发人员做参考。

规范是死的,人是活的,希望自己定的规范,不要被打脸。


路由命名规范

动作前缀备注
获取getget{XXX}
获取getget{XXX}List
新增addadd{XXX}
修改updateupdate{XXX}
保存savesave{XXX}
删除deletedelete{XXX}
上传uploadupload{XXX}
发送sendsend{XXX}

请求方式

请求方式描述
GET获取数据
POST新增数据
PUT更新数据
DELETE删除数据

请求参数

Query

url?后面的参数,存放请求接口的参数数据。

Header

请求头,存放公共参数、requestId、token、加密字段等。

Body

Body 体,存放请求接口的参数数据。

公共参数

APP 端请求

参数说明备注
network网络WIFI、4G
operator运营商中国联通/移动
platform平台iOS、Android
system系统ios 13.3、android 9
device设备型号iPhone XR、小米9
udid设备唯一标示
apiVersionAPI 版本号v1.1、v1.2

WEB 端请求

参数说明备注
appKey授权Key字符串

调用方需向服务方申请 appKey(请求时使用) 和 secretKey(加密时使用)。

安全规范

敏感参数加密处理

登录密码、支付密码,需加密后传输,建议使用非对称加密。

其他规范

  • 参数命名规范 建议使用驼峰命名,首字母小写。
  • requestId 建议携带唯一标示追踪问题。


返回参数

参数类型说明备注
codeNumber结果码成功=1<br/>失败=-1<br/>未登录=401<br/>无权限=403
showMsgString显示信息系统繁忙,稍后重试
errorMsgString错误信息便于研发定位问题
dataObject数据JSON 格式

若有分页数据返回的,格式如下

{
    "code": 1,
    "showMsg": "success",
    "errorMsg": "",
    "data": {
        "list": [],
        "pagination": {
            "total": 100,
            "currentPage": 1,
            "prePageCount": 10
        }
    }
}

安全规范

敏感数据脱敏处理

用户手机号、用户邮箱、身份证号、支付账号、邮寄地址等要进行脱敏,部分数据加 * 号处理。

其他规范

  • 属性名命名时,建议使用驼峰命名,首字母小写。
  • 属性值为空时,严格按类型返回默认值。
  • 金额类型/时间日期类型的属性值,如果仅用来显示,建议后端返回可以显示的字符串。
  • 业务逻辑的状态码和对应的文案,建议后端两者都返回。
  • 调用方不需要的属性,不要返回。


签名设计

签名验证没有确定的规范,自己制定就行,可以选择使用 对称加密、非对称加密、单向散列加密 等,分享下原来写的签名验证,供参考。


日志平台设计

日志平台有利于故障定位和日志统计分析。

日志平台的搭建可以使用的是 ELK 组件,使用 Logstash 进行收集日志文件,使用 Elasticsearch 引擎进行搜索分析,最终在 Kibana 平台展示出来。


幂等性设计

我们无法保证接口的每一次调用都是有返回结果的,要考虑到出现网络异常的情况。

举个例子,订单创建时,我们需要去减库存,这时接口发生了超时,调用方进行了重试,这时是否会多扣一次库存?

解决这类问题有 2 种方案:

一、服务方提供相应的查询接口,调用方在请求超时后进行查询,如果查到了,表示请求处理成功了,没查到就走失败流程。

二、调用方只管重试,服务方保证一次和多次的请求结果是一样的。

对于第二种方案,就需要服务方的接口支持幂等性。

大致设计思路是这样的:

  1. 调用接口前,先获取一个全局唯一的令牌(Token)
  2. 调用接口时,将 Token 放到 Header 头中
  3. 解析 Header 头,验证是否为有效 Token,无效直接返回失败
  4. 完成业务逻辑后,将业务结果与 Token 进行关联存储,设置失效时间
  5. 重试时不要重新获取 Token,用要上次的 Token


小结

限流设计、熔断设计、降级设计,这些就不多说了,因为大部分都用不到,当用上了基本上也都在网关中加这些功能。

暂时就想到这么多,规范这东西不是一成不变的,发现有不妥的及时调整吧。

你们接口的输入输出 Key,命名是用驼峰还是下划线?欢迎留言。



推荐阅读

原文:https://segmentfault.com/a/1190000021823944


链接: https://fly63.com/article/detial/7646

浏览器中的图像识别 API

在 Native 开发中,Android 和 IOS 平台都在系统层面直接提供给了应用开发识别图像的一些能力,比如对于二维码/条形码的识别,Android 可以使用 barcode API 、 iOS 可以使用 CIQRCodeFeature API 。

JavaScript的API设计原则

Js的API设计原则总共包含了七个大块。系卤煮自己总结的一些经验和教训。本篇博文同时也参考了其他一些文章,相关地址会在后面贴出来。很难做到详尽充实,如果有好的建议或者不对的地方,还望不吝赐教斧正。

适合写api接口文档的管理工具有哪些?

现在越来越流行前后端分离开发,使用ajax交互。所以api接口文档就变的十分有意义了,目前市场有哪些比较优秀的接口文档管理工具呢?比如:MinDoc,eoLinker,apizza,RAML,Swagger等等

前后端分离,如何防止api接口被恶意调用或攻击

无论网站,还是App目前基本都是基于api接口模式的开发,那么api的安全就尤为重要了。目前攻击最常见的就是“短信轰炸机”,由于短信接口验证是App,网站检验用户手机号最真实的途径,使用短信验证码在提供便利的同时,也成了呗恶意攻击的对象,那么如何才能防止被恶意调用呢?

JSON API免费接口_ 免费的天气预报、地图、IP、手机信息查询、翻译、新闻等api接口

整理提供最新的各种免费JSON接口,其中有部分需要用JSONP调用。方面前端同学的学习或在网站中的使用,包括:免费的天气预报、地图、IP、手机信息查询、翻译、新闻等api接口

什么是RESTful API?

要弄清楚什么是RESTful API,首先要弄清楚什么是REST。REST -- REpresentational State Transfer,英语的直译就是“表现层状态转移”。如果看这个概念,估计没几个人能明白是什么意思。

认识 Fetch API

Fetch API 已经作为现代浏览器中异步网络请求的标准方法,其使用 Promise 作为基本构造要素。Fetch 在主流浏览器中都有很好的支持,除了IE。

用一个通俗的例子讲清楚API

随着移动互联网的发展, 基于互联网的应用正变得越来越普及,在这个过程中,更多的平台将自身的资源开放给开发者来调用。对外提供的API 调用使得平台之间的内容关联性更强,同时这些开放的平台也为用户、开发者和中小网站带来了更大的价值。

docker提供api访问

环境centos,添加deamon.json后,dockerd命令可以启动docker,这时请求 127.0.0.1:2375 可以正常访问,使用systemctl无法启动docker的情况.无法启动docker:查看当前的docker配置

构建API的最佳编程语言是什么?

你是否正在设计第一个Web应用程序?也许你过去已经建立了一些,但是目前也正在寻找语言的变化以提高你的技能,或尝试新的东西。有了所有信息,就很难决定为下一个产品或项目选择哪种编程语言。

点击更多...

内容以共享、参考、研究为目的,不存在任何商业目的。其版权属原作者所有,如有侵权或违规,请与小编联系!情况属实本人将予以删除!