转：

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版本管理中的沟通问题

API版本管理中的沟通问题的更多相关文章

  1. 第 13 篇：DRF 框架之 API 版本管理

    作者:HelloGitHub-追梦人物 API 不可能一成不变,无论是新增或者删除已有 API,都会对调用它的客户端产生影响.如果对 API 的增删没有管理,随着 API 的增增减减,调用它的客户端就 ...

  2. [译] 在Web API 2 中实现带JSON的Patch请求

    原文链接:The Patch Verb in Web API 2 with JSON 我想在.NET4.6 Web API 2 项目中使用Patch更新一个大对象中的某个字断,这才意识到我以前都没有用 ...

  3. Web API项目中使用Area对业务进行分类管理

    在之前开发的很多Web API项目中,为了方便以及快速开发,往往把整个Web API的控制器放在基目录的Controllers目录中,但随着业务越来越复杂,这样Controllers目录中的文件就增加 ...

  4. [Android Pro] Android API 23中废弃了HttpClient的解决办法

    reference to : http://blog.csdn.net/hbwindy/article/details/51326019 reference to : http://blog.csdn ...

  5. Javacard 解释器怎样在API类库中找到源文件调用的类、方法或者静态域？

    申明:本篇非本人原创,是在阅读各种论文文献之后,对论文文献的一种梳理. 主要参考文献为: ------------------------------------------------------- ...

  6. ASP.NET Web API 2 中的属性路由使用（转载）

    转载地址:ASP.NET Web API 2 中的属性路由使用

  7. Web API 2中的属性路由

    Web API 2中的属性路由 前言 阅读本文之前,您也可以到Asp.Net Web API 2 系列导航进行查看 http://www.cnblogs.com/aehyok/p/3446289.ht ...

  8. 通读cheerio API ——NodeJs中的jquery

    通读cheerio API ——NodeJs中的jquery 所谓工欲善其事,必先利其器,所以通读了cheerio的API,顺便翻译了一遍,有些地方因为知道的比较少,不知道什么意思,保留了英文,希望各 ...

  9. ASP.NET Core Web API 集成测试中使用 Bearer Token

    在 ASP.NET Core Web API 集成测试一文中, 我介绍了ASP.NET Core Web API的集成测试. 在那里我使用了测试专用的Startup类, 里面的配置和开发时有一些区别, ...

随机推荐

  1. hdu4325 Flowers

    Problem Description As is known to all, the blooming time and duration varies between different kind ...

  2. 搭建基于springboot轻量级读写分离开发框架

    何为读写分离 读写分离是指对资源的修改和读取进行分离,能解决很多数据库瓶颈,以及代码混乱难以维护等相关的问题,使系统有更好的扩展性,维护性和可用性. 一般会分三个步骤来实现: 一. 主从数据库搭建 信 ...

  3. 【ybt金牌导航1-2-4】免费馅饼

    免费馅饼 题目链接:ybt金牌导航1-2-4 题目大意 有一个直线,在某一个时刻有一个馅饼会出现在一些位置,有它的价值. 一个人一开始可以站在直线的任意地方,然后他每个时刻可以不移动,或向任意一边移动 ...

  4. CF1474-D. Cleaning

    CF1474-D. Cleaning 题意: 给出一个长度为\(n\)的正整数序列,你可以对序列进行如下操作: 对序列中相邻的两个数字\(a_{i}, a_{i+1}\)同时减去一个数字\(t(t&l ...

  5. eclispe中解决OOM问题

     -Xms256M -Xmx512M -XX:PermSize=256m -XX:MaxPermSize=512m 

  6. 牛客网多校第9场 E Music Game 【思维+数学期望】

    题目:戳这里 题意:鼠标点击n下,第i次点击成功的概率为p[i],连续点击成功x次可以获得x^m分,求n次点击总分数的数学期望. 解题思路:数学期望的题很多都需要转化思维,求某一个单独状态对整体答案的 ...

  7. POJ1273 最大流模板

    之前自己写的,以后当一个模板的基础吧,不管是最大流,最小割,二分图匹配 下面是POJ1273的一个裸题.. 1 #include <iostream> 2 #include <cst ...

  8. vue stop event bug

    vue stop event bug [Vue warn]: Error in v-on handler: "TypeError: e.prevntDefault is not a func ...

  9. 快速下载 Visual Studio Code

    快速下载 Visual Studio Code https://visualstudio.microsoft.com/zh-hant/downloads/ 切换 cdn https://az76429 ...

  10. 23 种设计模式 APP & 23 Design Patterns App

    23 种设计模式 APP & 23 Design Patterns App https://github.com/xgqfrms/23-design-patterns-app https:// ...