转:

API版本管理中的沟通问题

产品升级会涉及API的更改,当API改动较大时,最大的问题是如何通知API的使用者(内部人员与使用OPENAPI 的用户),我们不能强迫所有用户立即对API的更改做出调整,但是也不能无限期的使用旧版本的API。

所以,一旦在生产环境中运行了多个API版本,通知使用者升级则成了一个大问题,复杂程度也与使用者的规模有关。意识到任何重大的更改对API的潜在影响,保持与用户群良好的关系至关重要。

尽管没有明确的规定多长时间需要更新API版本,但是考虑到整个团队,强烈建议在任何给定的时间内生产中的主要API版本永远不要超过两个。这可以让团队每次需要升级版本时都具有一致且可靠的转换过程,而不必担心管理太多且看似随机的API。

不管给定多少版本的API,清楚的传达与API版本更新相关的时间和更改内容是确保顺利升级的关键。API弃用通知应该尽早发送给使用者,通常是在新的API版本准备发布前,消息应包括所有内容,例如正在进行的更改,影响到哪些更新,使用者需要采取哪些操作来避免任何出现的问题。

如何才能快速并且及时的通知用户API更新信息。由于使用用户的环境不同,有些用户是离线环境,有些则是规定使用某一类型文档,导致API文档有很多种形式,例如:HTML、WORD文档、EXCEL文档…还包括一些热门的在线文档、API文档工具,如swagger、eolinker等。如果您的文档以某一格式类型存在,制作一份文档则需要制作不同格式而内容相同的文档,工作量是很大的。

API文档工具可以帮助我们解决以上问题,以Eolinker为例,在保持文档清晰可读的同时,Eolinker可以在线分享文档,或导出多种格式文档,并支持通知…大大降低了工作量,Eolinker是一个适配不同规模团队的Saas工具,同时也支持私有化部署。
使用地址:www.eolinker.com

转:

API版本管理中的沟通问题

最新文章

  1. 在github分支上上传空文件夹
  2. gulp外挂 uglify 的使用
  3. 怎么样使用yum来安装、卸载jdk
  4. Linux统计文件行数
  5. Java 7 Concurrency Cookbook 翻译 第一章 线程管理之二
  6. Maven学习(三) -- 仓库
  7. CentOS6.4 安装 erlang
  8. 转:python webdriver API 之层级定位
  9. canvas实现音乐中的歌词播放效果
  10. 57.DDR3的系统时钟编译错误
  11. Ant编译环境
  12. c语言中static的用法
  13. IText 生成简单表格(报表)doc文档 单元居中
  14. Elasticsearch基础概念理解
  15. 韩玉琪 《Linux内核分析》MOOC课程
  16. Java中接口与实例化
  17. HDU_2039——判断三条边是否能组成三角形
  18. mongodb操作之使用javaScript实现多表关联查询
  19. java对象拷贝和复制
  20. Flask 框架介绍

热门文章

  1. pta—紧急救援 (dijkstra)
  2. Codeforces Round #529 (Div. 3) D. Circular Dance (思维)
  3. CF1474-D. Cleaning
  4. 国产网络损伤仪SandStorm -- 如何连接设备
  5. Java容器--2021面试题系列教程(附答案解析)--大白话解读--JavaPub版本
  6. Chrony时间同步
  7. Nginx基础 - 配置静态web服务
  8. docker的网络-单主机(三种原生网络)none、host、bridge
  9. C++ part8
  10. Spring-cloud-netflix-hystrix