您当前的位置:首页 > 电脑百科 > 程序开发 > 编程百科

API 接口设计规范

时间:2019-09-09 11:12:03  来源:  作者:
API 接口设计规范

 

协议

http
https(使用HTTPS协议,以确保交互数据的传输安全)

域名

专门的api应用使用独立域名 https://api.example.com
简单的可使用api前缀区分 https://www.example.com/api

版本控制

接口版本的控制,可以在程序发布时,不同版本的业务逻辑在一定程度上避免受到影响。

https://api.example.com/v{n}
  • 应该将API的版本号放入URL。
  • 采用多版本并存,增量发布的方式。
  • n代表版本号,分为整型和浮点型
  • 整型: 大功能版本, 如v1、v2、v3 ...
  • 浮点型: 补充功能版本, 如v1.1、v1.2、v2.1、v2.2 ...

URL规则

  • 在RESTful架构中,每个网址代表一种资源(resource),所以网址中不能有动词,只能有名词。 【所用的名词往往与数据库的表格名对应】
  • 数据库中的表一般都是同种记录的"集合"(collection),所以API中的名词也应该使用复数。
例子
https://api.example.com/v1/products
https://api.example.com/v1/users
https://api.example.com/v1/employees

请求方式

  • GET(SELECT): 从服务器取出资源(一项或多项)。
  • POST(CREATE): 在服务器新建一个资源。
  • PUT(UPDATE): 在服务器更新资源(客户端提供改变后的完整资源)。
  • DELETE(DELETE): 从服务器删除资源。
 例子: 
 GET /v1/products 获取所有商品
 GET /v1/products/ID 获取某个指定商品的信息
 POST /v1/products 新建一个商品
 PUT /v1/products/ID 更新某个指定商品的信息
 DELETE /v1/products/ID 删除某个商品
 GET /v1/products/ID/purchases 列出某个指定商品的所有投资者
 GET /v1/products/ID/purchases/ID 获取某个指定商品的指定投资者信息

方法命名也要具有一定规范

  • 新增 以“add”为前缀。例如add{XXX}
  • 删除 以“delete”为前缀。例如delete{XXX}
  • 修改 以“updata”为前缀。例如updata{XXX}
  • 获取 以“get”为前缀。例如get{XXX}
  • 获取 以“get”为前缀、“List”为后缀。例如get{XXX}List
  • 保存 以“save”为前缀。例如save{XXX}
  • 发送 以“send”为前缀。例如send{XXX}
  • 上传 以“upload”为前缀。例如upload{XXX}

请求参数

  • cookie
  • request header: 可以存放requestId,token,加密字段等
  • 请求body数据 :针对入参数据,后端必须做数据验证
  • 地址栏参数

响应格式

response:

----------------------------------------

{
 status: 200, // 详见【status】
 data: {
 code: 1, // 详见【code】
 data: {} || [], // 数据
 message: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】
 sysMessage: 'success' // 存放响应信息提示,调试使用,中英文都行
 ... // 其它参数,如 total【总记录数】等
 },
 msg: '成功', // 存放响应信息提示,显示给客户端用户【须语义化中文提示】
 sysMsg: 'success' // 存放响应信息提示,调试使用,中英文都行
}

status

200: OK 
400: Bad Request 
500:Internal Server Error 
401:Unauthorized 
403:Forbidden 
404:Not Found

code

 1: 获取数据成功 | 操作成功 
 0:获取数据失败 | 操作失败

前后端约定

后端

  • 后端需要保证JSON格式的合法性,前端不对格式的合法性做判断
  • 金额格式:所有金额以元为单位,显示性的后台返回的是格式化之后的,例如:6,800
  • 时间格式: 尽量以一致格式的字符串传递 2019-01-01 12:12:12
  • 数据接口中定义的key集合是后端返回的子集,即key不缺失(参考数据格式,允许传递更多数据)
  • key使用驼峰命名,首字母小写
  • 空对象请使用[]
  • 空列表请使用[]
  • 空字符串请使用''
  • 默认数字请使用0
  • 尽量避免使用null undefined
  • 响应头Content-Type为"Application/json; charset=UTF-8"
  • 接口应该携带requestId唯一标示用来追踪问题
  • 敏感度高的数据,客户端和服务器通过约定的算法,对传递的参数值进行签名匹配,防止参数在请求过程中被抓取篡改。
  • 包含用户隐私的字段数据,需要加*号。如:手机号,身份证,用户邮箱,支付账号,邮寄地址等。
 "phone":"150*****000",
 "idCard":"3500**********0555", 
 "email":"40*****00@qq.com" 

前端

  • 请求头 application/x-www-form-urlencoded
  • 请求字段使用驼峰命名,首字母小写
  • 一个页面尽量只有一个拉取接口,减少类似这种的连续请求。
  • 当请求需要缓存并且有需要及时更新的情况,可以分多个请求。

文档

这个无需多说,在系统对接的时候,有文档绝对是个福音。

  • 尽量采用自动化接口文档,可以做到在线测试,同步更新。
  • 应包含:接口BASE地址、接口版本、接口模块分类等。
  • 每个接口应包含: 接口地址:不包含接口BASE地址。 请求方式: get、post、put、delete等。 请求参数:数据格式【默认JSON、可选form data】、数据类型、是否必填、中文描述。 响应参数:类型、中文描述。
  • 特殊code映射码表

瘦客户端

客户端任何的修改都是需要发版的,发版需要审核流程。

  • 客户端尽量只负责展示逻辑,不处理业务逻辑
  • 客户端不处理金额的计算
  • 客户端少处理请求参数的校验与约束提示

接口日志

方便故障定位,错误重放,日志统计分析等

上传/下载

上传/下载,参数增加文件md5,用于完整性校验

性能优化

合并接口

字段简写

无用字段清理

图片裁剪

局部刷新

预加载

其他

接口安全,防参数篡改

频率的控制

数据存储

是否需要依赖于第三方

服务降级,熔断和限流

拆分

扩展性

适配性

幂等

重复提交

部署

缓存穿透、缓存雪崩和缓存击穿

是否需要白名单

预加载

重试

异步

服务端推送或者客户端拉取数据

隔离(例如内网的中台服务,后端服务)

健康检查,后台大盘监控可视化,故障主动通知



Tags:API   点击:()  评论:()
声明:本站部分内容来自互联网,转载是出于传递更多信息之目的,内容观点仅代表作者本人,如有任何标注错误或版权侵犯请与我们联系,我们将及时更正、删除,谢谢。
▌相关评论
发表评论 共有条评论
用户名: 密码:
验证码: 匿名发表
▌相关推荐
在6月中旬时,拼多多为了保障数据安全和运营信息安全,依据《拼多多开放平台开发者协议》等相关协议和规则,发布了对商家在使用API接口的时候开始收费的公告。 所谓API,百度百科...【详细内容】
2020-07-09   API  点击:(3)  评论:(0)  加入收藏
什么是百度Geocoding API?Geocoding API是一个供程序员调用的、http形式的地图服务接口。主要服务那些非网页程序的调用。例如C# 、C++、Java等开发语言都能发送http请求且能...【详细内容】
2020-07-05   API  点击:(1)  评论:(0)  加入收藏
想知道API的使用在当今的软件开发过程中有多普遍?那就去问问工程师们在他们的项目中集成了多少API吧。大多数开发团队可能不知道确切的答案。然而我们知道,从分析工具到地图应用和云托管,现代应用程序都使用了大量的内部...【详细内容】
2020-06-25   API  点击:(0)  评论:(0)  加入收藏
使用微服务模式构建应用程序并将这些服务部署到Kubernetes上已成为当今运行云原生应用程序的实际方法。 在微服务架构中,单个应用程序被分解为多个微服务。 每个微服务均由...【详细内容】
2020-06-22   API  点击:(1)  评论:(0)  加入收藏
RESTful API无处不在,比任何其他API体系结构都为现代世界提供了更多支持。 根据ProgrammableWeb的研究,REST占API的80%。 这些API的构建和结构方式可以在当今竞争异常激烈的世...【详细内容】
2020-06-21   API  点击:(2)  评论:(0)  加入收藏
有没有遇到这样子的接口,放到互联网上面去,谁都可以调用,谁都可以访问,完全就是公开的,这样子的接口,如果只是普通的数据,其实可以考虑,只是可以考虑,但是,一般情况下,我们是不允许这样...【详细内容】
2020-06-20   API  点击:(4)  评论:(0)  加入收藏
一个api网关项目,可以当做api开放平台或外网转内网的转发工具 (仅支持http/https转发,基于HttpClient4.5),1、完全开源免费 2、基于appKey+appSecret的账号 3、api支持通配符匹...【详细内容】
2020-06-16   API  点击:(1)  评论:(0)  加入收藏
Apache ShardingSphere 的 5.x 版本正在开发中,其中 API 的设计是重中之重。目前大部分 API 都已定型,对于用户使用最广泛的分片算法 API,目前也已经做了较大幅度的更新。5.x...【详细内容】
2020-06-15   API  点击:(0)  评论:(0)  加入收藏
相关名词剖析随着互联网的快速发展,企业的IT建设也是飞速发展的,但是在建设企业信息化时没有统筹考虑,建设往往不成体系、重复开发、烟囱式的建设,造成了资源的冗余和浪费,为了针...【详细内容】
2020-06-13   API  点击:(67)  评论:(0)  加入收藏
随着软件规模的日益庞大,常常需要把复杂的系统划分成小的组成部分,编程接口的设计十分重要,程序设计的实践中,编程接口的设计首先要使软件系统的职责得到合理划分,良好的接口设计...【详细内容】
2020-06-06   API  点击:(2)  评论:(0)  加入收藏
滑动验证是网站反爬虫、反作弊的升级,滑动验证也是机器学习在反爬虫、反作弊领域的应用; 本项目也是一个简单的全栈项目,使用tornado做的后端、Bootstrap4做的前端;核心的识别...【详细内容】
2020-06-04   API  点击:(0)  评论:(0)  加入收藏
问题的起源在直播服务中,有一个敏感词的检测的需求:当用户发送聊天消息之前,调用接口验证消息是否包含敏感词,我们使用了阿里云的文本安全服务,这是一个按照次数收费的服务,所以接...【详细内容】
2020-05-13   API  点击:(4)  评论:(0)  加入收藏
一个api网关项目,可以当做api开放平台或外网转内网的转发工具 (仅支持http/https转发,基于HttpClient4.5),1、完全开源免费 2、基于appKey+appSecret的账号 3、api支持通配符匹...【详细内容】
2020-05-06   API  点击:(8)  评论:(0)  加入收藏
早上开完站会,小李领了张新卡,要对登录功能做升级改造,在原来只支持用户名密码登录模式的基础上,新增手机号和短信验证码登录。...【详细内容】
2020-04-24   API  点击:(6)  评论:(0)  加入收藏
前几天,作者遇到了这样一种情况,需要在一个让web3.py几乎不可能工作的环境中使用Python与Ethereum网络进行通信。...【详细内容】
2020-04-23   API  点击:(8)  评论:(0)  加入收藏
前言假设你正在开发一个电商网站,那么这里会涉及到很多后端的微服务,比如会员、商品、推荐服务等等。 那么这里就会遇到一个问题,APP/Browser怎么去访问这些后端的服务? 如果...【详细内容】
2020-04-11   API  点击:(0)  评论:(0)  加入收藏
API产品的认证部分应该如何设计?本文结合作者自己的工作实践经历,对身份验证、对称签名身份验证、非对称加密的签名认证三种方式进行了分析,与大家分享。做平台产品,绕不开API。...【详细内容】
2020-04-10   API  点击:(8)  评论:(0)  加入收藏
一、APISIX相关介绍1、安全网关安全网关设置的目的是防止Internet或外网不安全因素蔓延到自己企业或组织的内部网 。安全网关在应用层和网络层上面都有防火墙的身影。其范围...【详细内容】
2020-04-07   API  点击:(22)  评论:(0)  加入收藏
一、APISIX相关介绍1、安全网关安全网关设置的目的是防止Internet或外网不安全因素蔓延到自己企业或组织的内部网 。安全网关在应用层和网络层上面都有防火墙的身影。其范围...【详细内容】
2020-04-07   API  点击:(5)  评论:(0)  加入收藏
一、APISIX相关介绍1、安全网关安全网关设置的目的是防止Internet或外网不安全因素蔓延到自己企业或组织的内部网 。安全网关在应用层和网络层上面都有防火墙的身影。其范围...【详细内容】
2020-04-07   API  点击:(6)  评论:(0)  加入收藏
最新更新
栏目热门
栏目头条