首页 > 其他分享 >API 接口设计规范

API 接口设计规范

时间:2023-08-10 14:58:40浏览次数:50  
标签:加密 请求 XXX 接口 Token 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 种方案:

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

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

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

大致设计思路是这样的:

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

小结

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

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

 

标签:加密,请求,XXX,接口,Token,API,参数,设计规范
From: https://www.cnblogs.com/Noah-1723045498/p/17620298.html

相关文章

  • [学习笔记] JS验证API相关知识
    checkValidity()会检查元素是否有任何输入约束条件,并且检查值是否符合约束条件。 如下所示,Input元素下限为4上限为20:···<inputid="password"type="number"min="4"max="20">···<script>functionmyFunction(){varx=document.getElementById(&quo......
  • openai API
    工具首先你得有一个key,这里获取key的方法就不做赘述调试工具postman(其他的也行)创建聊天参数说明类型可选值默认值必传model聊天模型string--是messages聊天记录array--是temperature使用什么采样温度,介于0和2之间。较高的值(如0.8)将使输出更加随机,而较低的值(如0.2)将使输......
  • 开发基于RESTful API的ASP.NET Web应用程序
    当开发基于RESTfulAPI的ASP.NETWeb应用程序时,您将构建一个可以通过HTTP请求进行交互的应用程序,它可以提供数据和功能给客户端应用程序或其他服务。在本博客中,我将为您提供一个基本的教程,演示如何创建一个简单的ASP.NETWeb应用程序,并实现基于RESTfulAPI的功能。步骤1:设置开发环......
  • 【看表情包学Linux】系统下的文件操作 | 文件系统接口 | 系统调用与封装 | open,write
      ......
  • mysql Statement接口
    Statement接口是Java执行数据库操作的一个重要接口,用于在已经建立数据库连接的基础上,向数据库发送要执行的SQL语句。java.sql.Statement接口用于执行静态的SQL语句并返回执行结果。在默认情况下,同一时间每个Statement接口只能打开一个ResultSet对象。因此,如果读取一个ResultSet......
  • 重学JavaScript Promise API
    在这篇教程中,我们将掌握如何在JavaScript中创建并使用Promise。我们将了解Promise链式调用、错误处理以及最近添加到语言中的一些Promise静态方法。什么是Promise?在JavaScript中,一些操作是异步的。这意味着当这些操作完成时,它们产出的结果或者值并不会立即生效。Promise是一......
  • 一文看懂Apipost接口自动化使用方法
    随着项目研发进程的不断推进,软件功能不断增多,对于软件测试的要求也越来越高。为了提高测试效率和减少测试成本,许多软件测试团队借助于自动化测试工具来优化测试流程。Apipost也提供了自动化测试工具,在本文中,我们将探讨如何借助Apipost自动化测试工具来优化测试流程。Apipost是一......
  • 一文看懂Apipost接口自动化使用方法
    随着项目研发进程的不断推进,软件功能不断增多,对于软件测试的要求也越来越高。为了提高测试效率和减少测试成本,许多软件测试团队借助于自动化测试工具来优化测试流程。Apipost也提供了自动化测试工具,在本文中,我们将探讨如何借助Apipost自动化测试工具来优化测试流程。Apipost是......
  • FastAPI入门引导
    FastAPI是一个现代、快速(高性能)的Web框架,用于基于标准Python类型提示使用Python3.7+构建API。主要特点是:快速:非常高的性能,与NodeJS和Go相当(感谢Starlette和Pydantic)。可用的最快的Python框架之一。快速编码:将开发功能的速度提高约200%至300%。*更少的错误:减少约4......
  • whistle修改接口返回步骤(只影响前端展示,不会插入数据到数据库)
    一、安装node、whistle安装教程:http://wproxy.org/whistle/install.html二、抓包/修改接口返回手机端抓包/修改接口返回步骤与web端类似。Web端抓包/修改接口返回1、下载证书启动whistle:在控制台中输入w2start即可启动whistle。点击whistle页面菜单中的HTTPS,点击二维码,即可下载......