接口对接文档规范2023年最新版（Restful API风格）
接口对接文档
- 服务共享
1、设计模式
使用Restful API风格, Restful API的优势是具备更好的易用性，让异构系统更容易集成，且开发执行效率比较高，面向资源要求也比较高。
2、设计约束
2.1 协议约束
这里的协议是指API与用户的通信协议，建议使用HTTPS协议。
2.2 URI约束
URI统一资源标识符是一个用于标识某一互联网资源名称的字符串。该种标识允许用户对任何（包括本地和互联网）的资源通过特定的协议进行交互操作。URI由包括确定语法和相关协议的方案所定义。Web上可用的每种资源-HTML文档、图像、视频片段、程序等-由一个通用资源标识符（Uniform Resource Identifier, 简称"URI"）进行定位。
现定义URI规范如下：
- 不使用大写。
- 用中杠-不用下杠_。
- 参数列表要encode
- URI中的名词表示资源集合，使用复数形式
- URI表示资源的两种方式：资源集合、单个资源。比如：
A: 资源集合：
/zoos //所有动物园
/zoos/1/animals //id为1的动物园中的所有动物
B: 单个资源：
/zoos/1 //id为1的动物园
- 路径层级小于三层，避免层级过深。
/在url中表达层级，用于按实体关联关系进行对象导航，一般根据id导航。
过深的导航容易导致url膨胀，不易维护，如 GET /zoos/1/areas/3/animals/4，尽量使用查询参数代替路径中的实体导航，如GET /animals?zoo=1&area=3；
- 组合资源的访问必须通过父实体的id导航访问。
组合实体不是first-class的实体，它的生命周期完全依赖父实体，无法独立存在，在实现上通常是对数据库表中某些列的抽象，不直接对应表，也无id。一个常见的例子是 User— Address，Address是对User表中zipCode/country/city三个字段的简单抽象，无法独立于User存在。必须通过User索引到Address：GET /user/1/addresses
2.3 请求方式
通过标准HTTP方法对资源CRUD，禁用一种访问方式进行多种形式的资源操作。建议采用GET获取某个资源，采用POST新建某个资源。其他请求方法不建议使用。
（1）GET请求：
- 查询可能附带的约束：过滤条件，排序，投影，分页等。
比如：?size=10¤t=1
- 复杂查询：经常使用的、复杂的查询标签化，降低维护成本。
比如：GET /trades/recently-closed
（2）POST：创建单个资源（注：POST一般向“资源集合”型uri发起，如果是组合资源一般向父级实体发起）
2.4 数据格式
使用常用的数据格式，这里建议使用：
Content-Type： application/json;charset=UTF-8
2.5 请求内容
基于不通的请求方式GET或者POST，使用不同的参数内容。
如使用GET方式请求参数使用Query参数。参数列表要使用encode格式化。如果存在分页查询，分页参数这里限定使用size表示每页记录数，使用current表示第几页。
如使用POST方式请求参数使用request body形式提交参数，请求体使用json格式。
备注：不允许存在空的请求参数，比如：{}，这种方式是不允许的，默认需要存在一个必填的参数，其它参数可非必填。
2.6 响应状态
HTTP 应答中，需要带一个很重要的字段：status code。它说明了请求的大致情况，是否正常完成、需要进一步处理、出现了什么错误，对于客户端非常重要。状态码都是三位的整数，大概分成了几个区间：
2XX：请求正常处理并返回
3XX：重定向，请求的资源位置发生变化
4XX：客户端发送的请求有错误
5XX：服务器端错误
2.7 错误处理
1、不要发生了错误但给2xx响应，客户端可能会缓存成功的http请求；
2、正确设置http状态码，不要自定义；
3、Response body 提供错误的描述文本(展示给用户)。
API 可能抛出两类异常：业务异常和非业务异常。业务异常由自己的业务代码抛出，表示一个用例的前置条件不满足、业务规则冲突等，比如参数校验不通过、权限校验失败。非业务类异常表示不在预期内的问题，通常由类库、框架抛出，或由于自己的代码逻辑错误导致，比如数据库连接失败、空指针异常、除0错误等。
业务类异常必须提供2种信息：
(1)如果抛出该类异常，对业务类异常，用它指定的 HTTP code；对非业务类异常，统一500；
(2)异常的文本描述；
需要在Controller层使用统一的异常拦截器：
Response Body 的错误描述：对业务类异常，用它指定的错误文本；对非业务类异常，线上可以统一文案如“服务器端错误，请稍后再试”，针对非业务类异常，应该在 Response body 中通过 msg 给出明确的错误信息(一般来说，返回的信息中将 msg 作为键名，出错详情作为键值即可)。比如客户端发送的请求有错误，一般会返回 4XX Bad Request 结果。这个结果很模糊，给出错误 msg 的话，能更好地让客户端知道具体哪里有问题，进行快速修改。错误信息应该是代码处理后的错误描述，不应该返回程序自动抛出的错误信息。
2.8 响应内容
响应的数据内容应该有标准的JSON输出格式
1、响应基本格式
{
"code": "xxx",
"msg": "xxx",
"data": { }
}
code：表示返回状态。
message: 表示返回消息提示
data：表示返回消息体，如果为数组，则表现为[]。
Code状态统一限定三类，其他响应参数值可自行扩展。
100000：成功响应
100003：失败响应
100005：查询空值
2、响应实体格式
{
"code": "100000",
"msg": "请求成功",
"data": {
"key1"："xxx",
"key2"："xxx"
}
}
Data表示为具体返回的实体类。
3、响应列表格式
{
"code": "100000",
"msg": "请求成功",
"data": [
{
"key1"："xxx",
"key2"："xxx"
},
……
]
}
Data表示具体返回的列表数据。
4、响应分页格式
{
"code": "100000",
"msg": "请求成功",
"data": {
"records"：[
{
"key1"："xxx",
"key2"："xxx"
},
……
]
,
"total": 100,
"size": 10,
"current": 1,
"pages": 10,
"其他参数": xxx,
……
}
Data：分页的具体记录集合。
Total:表示总记录数。
Size：表示分页的记录数
Current：表示当前第几页
Pages：表示总分页数
其他参数可以自行扩展。
- 服务订阅
- 基础架构
EMQ是基于物联网 MQTT（消息队列遥测传输协议） 的消息代理服务。MQTT消息队列遥测传输协议，是一种基于发布/订阅模式的"轻量级"通讯协议，该协议构建于TCP/IP协议。我们这里使用发布订阅（PubSub）模式消息服务器，基于主题（Topic）进行消息路由。
- 数据传输
MQTT传输的消息分为：主题（Topic）和负载（payload）两部分：
（1）Topic，可以理解为消息的类型，订阅者订阅（Subscribe）后，就会收到该主题的消息内容（payload）；
（2）payload，可以理解为消息的内容，是指订阅者具体要使用的内容。
- 客户端使用
使用MQTT协议建立到服务器的网络连接。此时可以操作如下内容：
（1）订阅指定Topic的消息内容；
（2）退订Topic；
（3）断开与服务器连接。
- 名词解释
4.1 订阅说明
订阅包含主题（Topic）和最大服务质量（QoS）。订阅会与一个会话（Session）关联。一个会话可以包含多个订阅。每一个会话中的每个订阅都有一个不同的主题。
4.2 会话说明
每个客户端与服务器建立连接后就是一个会话，客户端和服务器之间有状态交互。
4.3 主题说明
连接到一个消息通道的标签，该标签与服务器的订阅相匹配。服务器会将消息发送给订阅所匹配标签的每个客户端。
4.4 负载（Payload）
消息订阅者所具体接收的内容.
4.5 MQTT协议中的方法
MQTT协议中定义了一些方法，来于表示对确定资源所进行操作。主要方法有：
（1）Connect。等待与服务器建立连接。
（2）Disconnect。等待MQTT客户端完成所做的工作，并与服务器断开TCP/IP会话。
（3）Subscribe。等待完成订阅。
（4）UnSubscribe。等待服务器取消客户端的一个或多个topics订阅。
附上下载地址
https://download.csdn.net/download/alafqq/87360017
接口对接文档规范2023年最新版（Restful API风格）相关推荐
- 战神引擎php,战神引擎php接口对接文档
(战神引擎自带的lua的网站环境有漏洞,所以lua接口已经停用,请下载最新的php接口并根据本文档对接) ``` 重要的事情先说明: 角色名充值!!!不是账号充值 ``` 1. 将文件夹ymphp解压 ...
- 接口编写 文档规范 总结
正文: 一:协议规范 为进一步确保数据交互安全.正式地址(生产地址)必须遵循HTTPS协议. 二:域名规范 每个项目要有且仅有一个自己唯一的域名+端口.在项目配置文件中要添加静态变量专门进行存储. 如 ...
- JD京东物流电子面单接口对接文档-快递鸟
1.注册账号http://www.kdniao.com/reg 2.在官网登录进入用户管理后台,进行实名认证,开通接口 3.技术对接及联调(登陆官网使用调试平台进行测试.) 4.上线 1.接口类型 ...
- 深圳物流 inurl php id=,免费快递在线下单接口对接文档-(PHP)
/** * Json方式在线下单 */ function orderOnlineByJson(){ $requestData="{'LogisticsWeight':2.0,". ...
- RESTful API接口文档规范小坑
希望给你3-5分钟的碎片化学习,可能是坐地铁.等公交,积少成多,水滴石穿,谢谢关注. 前后端分离的开发模式,假如使用的是基于RESTful API的七层通讯协议,在联调的时候,如何避免配合过程中出现问 ...
- Swagger3 API接口文档规范课程（Java1234）（内含教学视频+源代码）
Swagger3 API接口文档规范课程(Java1234)(内含教学视频+源代码) 教学视频+源代码下载链接地址:https://download.csdn.net/download/weixin_ ...
- 算法API接口文档规范
算法API接口文档规范 参考:百度AI开放平台:https://ai.baidu.com/ai-doc/FACE/yk37c1u4t 接口功能介绍 1.人脸比对:比对两张图片中人脸的相似度,并返回相似 ...
- 【商品接口】淘宝一键铺货对接文档
淘宝一键铺货应用场景对接文档 测试方法(具体步骤请先查看文档:[ OAuth2.0接口对接>商品接口测试方法] 1.订购链接: 2.授权 拿到ssion_id 3.调用custom接口 免费注册 ...
- 第三方对接圆通物流轨迹查询接口开放文档
根据圆通物流运单号查询已有的快件物流信息,在物流信息里面会包含物流状态,如 [客户 **** 已签收],物流信息保持与官网一致. 快递鸟在途监控汇集国内外1600多家快递公司的物流轨迹数据,以接口形式 ...
最新文章
- python与人工智能编程-总算明白python人工智能编程入门案例
- 备份 CSDN 博客（上）
- 大数据、AI“武装”企业服务：风控、检索、安全
- Golang——深浅拷贝
- 分布式红锁的leaseTime的设计原理
- 使用JavaScript判断用户是否为手机设备
- mysql可视化_Mysql学习
- git maven 一键部署_jenkins+git+maven搭建自动化部署项目环境
- python的power,Python numpy.power()函数使用说明
- KeilC51基本关键字
- Java集成DataX
- 关于传播速率和传输速率的区别
- 1.21.3 经典车间生产调度问题智能生产系统中的调度问题
- python：matplotlib基础（3）
- CPU中的八个通用寄存器
- Go之Benchmark
- SAP HR Schema 详解（三）工资核算基础
- 涨知识了！苹果手机清理缓存原来这么简单，一键就能清出几个G
- Stack Overflow：开发者在周末更喜欢用哪个编程语言
- (小技巧) 如何让Linux 机器CPU使用率变高