API 接口设计规范

概述

这篇文章分享 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

小结

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

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

推荐阅读

原文地址:https://www.cnblogs.com/xinliangcoder/p/12327088.html

时间: 2024-11-10 13:01:25

API 接口设计规范的相关文章

restFull api接口

RestFull api接口 前后端分离开发的接口规范 什么是RestFull 是目录比较流行的api设计规范 注:restfull api规范应用场景,前后端分离的项目中 数据接口的现场 例如: /users/999 获取ID为999的信息 /users/list  获取所有的用户信息 /users/add  打开添加的页面 /users/save 新增数据 /users/edit 打开修改的页面 /users/save 根据表单是否有主键的值判断是否有更新 /users/del/999  删

微信小程序的Web API接口设计及常见接口实现

微信小程序给我们提供了一个很好的开发平台,可以用于展现各种数据和实现丰富的功能,通过小程序的请求Web API 平台获取JSON数据后,可以在小程序界面上进行数据的动态展示.在数据的关键 一环中,我们设计和编写Web API平台是非常重要的,通过这个我们可以实现数据的集中控制和管理,本篇随笔介绍基于Asp.NET MVC的Web API接口层的设计和常见接口代码的展示,以便展示我们常规Web API接口层的接口代码设计.参数的处理等内容. 1.Web API整体性的架构设计 我们整体性的架构设计

微信小程序API接口

微信小程序API接口 wx.request(OBJECT)   wx.request发起的是 HTTPS 请求. OBJECT参数说明: url->开发者服务器接口地址->String; data->请求的参数->Object.String; header->设置请求的 header , header 中不能设置 Referer->Object; method->默认为 GET,有效值:OPTIONS, GET, HEAD, POST, PUT, DELETE,

百度翻译APi接口实现

案例使用百度翻译API接口,实现文本翻译 为保证翻译质量,请将单次请求长度控制在 6000 bytes以内.(汉字约为2000个) 签名生成方法如下: 1.将请求参数中的 APPID(appid), 翻译query(q, 注意为UTF-8编码), 随机数(salt), 以及平台分配的密钥(可在管理控制台查看) 按照 appid+q+salt+密钥 的顺序拼接得到字符串1. 2.对字符串1做md5,得到32位小写的sign. 注意: 1.请先将需要翻译的文本转换为UTF-8编码 2.在发送HTTP

php后台对接ios,安卓,API接口设计和实践完全攻略,涨薪必备技能

2016年12月29日13:45:27 关于接口设计要说的东西很多,可能写一个系列都可以,vsd图都得画很多张,但是由于个人时间和精力有限,所有有些东西后面再补充 说道接口设计第一反应就是restful api 请明白一点,这个只是设计指导思想,也就是设计风格 ,比如你需要遵循这些原则 原则条件REST 指的是一组架构约束条件和原则.满足这些约束条件和原则的应用程序或设计就是 RESTful.Web 应用程序最重要的 REST 原则是,客户端和服务器之间的交互在请求之间是无状态的.从客户端到服务

总结的一些微信API接口

本文给大家介绍的是个人总结的一些微信API接口,包括微信支付.微信红包.微信卡券.微信小店等,十分的全面,有需要的小伙伴可以参考下. 1. [代码]index.php <?php include_once 'lib.inc.php';   $wcObj = new WeChat("YOUKUIYUAN"); $wcObj->wcValid(); 2. [代码]微信入口类 <?php /**  * Description of wechat  *  * @author

Thinkphp5使用api接口demo

阿里云有免费的手机归属地api接口,作为新手的博主决定使用该接口写一个手机归属地查询网站,学习api的使用. 主要思路: 获取前台传入的手机号->写出请求url,请求头,请求方式->初始化cURL变量->设置cURL变量参数->执行查询,保存返回的json数据->关闭查询连接->将json数据解析为php数组->将该php数组赋值到模板->前台调用该数组值. public function index() { $num=input('m'); //获取前台提

Restful风格API接口开发springMVC篇

Restful风格的API是一种软件架构风格,设计风格而不是标准,只是提供了一组设计原则和约束条件.它主要用于客户端和服务器交互类的软件.基于这个风格设计的软件可以更简洁,更有层次,更易于实现缓存等机制. 在Restful风格中,用户请求的url使用同一个url而用请求方式:get,post,delete,put...等方式对请求的处理方法进行区分,这样可以在前后台分离式的开发中使得前端开发人员不会对请求的资源地址产生混淆和大量的检查方法名的麻烦,形成一个统一的接口. 在Restful风格中,现

C++传智笔记(6):socket客户端发送报文接受报文的api接口

#define _CRT_SECURE_NO_WARNINGS #include "stdio.h" #include "stdlib.h" #include "string.h" #include "itcast_comm.h" #include "memwatch.h" #include "itcastlog.h" /* 下面定义了一套socket客户端发送报文接受报文的api接口