API 接口设计规范

标签: api 接口设计 规范 | 发表时间:2020-02-22 00:32 | 作者:訢亮
出处:https://juejin.im/welcome/backend

概述

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

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

路由命名规范

动作 前缀 备注
获取 get get{XXX}
获取 get get{XXX}List
新增 add add{XXX}
修改 update update{XXX}
保存 save save{XXX}
删除 delete delete{XXX}
上传 upload upload{XXX}
发送 send send{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 设备唯一标示
apiVersion API 版本号 v1.1、v1.2

WEB 端请求

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

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

安全规范

敏感参数加密处理

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

其他规范

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

返回参数

参数 类型 说明 备注
code Number 结果码 成功=1
失败=-1
未登录=401
无权限=403
showMsg String 显示信息 系统繁忙,稍后重试
errorMsg String 错误信息 便于研发定位问题
data Object 数据 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,命名是用驼峰还是下划线?欢迎留言。

推荐阅读

相关 [api 接口设计 规范] 推荐:

API 接口设计规范

- - 掘金后端
这篇文章分享 API 接口设计规范,目的是提供给研发人员做参考. 规范是死的,人是活的,希望自己定的规范,不要被打脸. url?后面的参数,存放请求接口的参数数据. 请求头,存放公共参数、requestId、token、加密字段等. Body 体,存放请求接口的参数数据. 调用方需向服务方申请 appKey(请求时使用) 和 secretKey(加密时使用).

接口设计评审规范 - 简书

- -
本接口设计规范,参考了restfull的部分设计理念. Restful API的核心元素,所有的操作都是针对特定资源进行的. 任何事物,只要有被引用到的必要,它就是一个资源. 资源可以是实体(例如手机号码),也可以只是一个抽象概念(例如价值). Github 可以说是这方面的典范,下面我们就拿. 资源分为单个文档和集合,尽量使用复数来表示资源,单个资源通过添加 id 或者 name 等来表示.

API接口设计之token、timestamp、sign具体实现

- - 企业架构 - ITeye博客
Token:访问令牌access token, 用于接口中, 用于标识接口调用者的身份、凭证,减少用户名和密码的传输次数. 一般情况下客户端(接口调用方)需要先向服务器端申请一个接口调用的账号,服务器会给出一个appId和一个key, key用于参数签名使用,注意key保存到客户端,需要做一些安全处理,防止泄露.

API 接口设计之 token+sign 具体架构与实现

- - 小决的专栏
在实际的业务中,难免会跟第三方系统进行数据的交互与传递,那么如何保证数据在传输过程中的安全呢(防窃取). 除了 https 的协议之外,能不能加上通用的一套算法以及规范来保证传输的安全性呢. Token:访问令牌 access token, 用于接口中,用于标识接口调用者的身份、凭证,减少用户名和密码的传输次数.

从 Feign 使用注意点到 RESTFUL 接口设计规范 - ImportNew

- -
最近项目中大量使用了Spring Cloud Feign来对接http接口,踩了不少坑,也产生了一些对RESTFUL接口设计的想法,特此一篇记录下. SpringMVC的请求参数绑定机制. 了解Feign历史的朋友会知道,Feign本身是Netflix的产品,Spring Cloud Feign是在原生Feign的基础上进行了封装,引入了大量的SpringMVC注解支持,这一方面使得其更容易被广大的Spring使用者开箱即用,但也产生了不小的混淆作用.

Api Blocking

- - xiaobaoqiu Blog
4.RateLimiter实现限流. 接口限流是保证系统稳定性的三大法宝之一(缓存, 限流, 降级).. 本文使用三种方式实现Api限流, 并提供了一个用Spring实现的Api限流的简单Demo, Demo的git地址: https://github.com/xiaobaoqiu/api-blocking.

股票API

- 狗尾草 - 博客园-首页原创精华区
股票数据的获取目前有如下两种方法可以获取:. http/javascript接口取数据. 1.http/javascript接口取数据. 以大秦铁路(股票代码:601006)为例,如果要获取它的最新行情,只需访问新浪的股票数据. 这个url会返回一串文本,例如:. var hq_str_sh601006="大秦铁路, 27.55, 27.25, 26.91, 27.55, 26.20, 26.91, 26.92, .

API 与 ABI

- Ant - A Geek's Page
(本文亦是《C语言编程艺术》中的一部分,所以请勿用于商业用途. 一些程序员居然对API和ABI这两个概念都不清楚,我感到有些惊讶. 这里以 Linux 内核为例简单解释一下. API,顾名思义,是编程的接口,换句话说也就是你编写“应用程序”时候调用的函数之类的东西. 对于内核来说,它的“应用程序”有两种:一种是在它之上的,用户空间的真正的应用程序,内核给它们提供的是系统调用这种接口,比如 read(2),write(2);另一种就是内核模块了,它们和内核处于同一层,内核给它们提供的是导出的内核函数,比如 kmalloc(),printk().

Google+ API发布

- 屁清新健脑 - Solidot
开发者终于等来了期待已久的Google+ API. Google正式发布了允许读取用户公开信息的API,开发者可以借助API开发与Google+交互的应用程序,或将其整合到网站上. Google社交网站发布2个月来,经历了用户暴涨,但也出现了热度下降. Google+ API的发布也许能给予它一个新动力.

API 之下

- - 阮一峰的网络日志
虽然标题里面有 API,但是本文谈的不是编程,而是更重要的事情. 很多公司的组织架构,都有一个中层. 高层领导和基层员工之间,存在大量的中层干部. 2015年,硅谷创业家 莱因哈特(Peter Reinhardt)观察到一个现象:硅谷科技公司正在变得越来越大,但是公司的中层几乎没有变大. 原因就在于,大公司正在用 API 替代掉中层干部.