转：

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. 2019 Multi-University Training Contest 1 A.Blank（dp）

    题意:现在要你构造一个只有{0,1,2,3} 长度为n且有m个限制条件的序列 问你方案数 思路:dp[i][j][k][now]分别表示四个数最后出现的位置 最后可以滚动数组 优化一下空间 ps:我的 ...

  2. 2018 ccpc吉林 The Tower

    传送门:HDU - 6559 题意 在一个三维空间,给定一个点和他的三维速度,给定一个圆锥,问这个点最早什么时候能撞上圆锥. 题解 本来一直想着怎么求圆锥的方程,然后....队友:这不是二分吗!然后问 ...

  3. cf1291c-Mind Control

    题意:n个数n个人依次取数,每个人只能取第一个数或最后一个数,你可以从一开始控制k个人取最前边或是最后边的数,你排在第m位,能取到的最大的数是多少.所有人取数都是最优策略(不是每次取最大数). 题解: ...

  4. AtCoder Beginner Contest 181 E - Transformable Teacher (贪心,二分)

    题意:有一长度为奇数\(n\)的数组\(a\),和长度为\(m\)的数组\(b\),现要求从\(b\)中选择一个数放到\(a\)中,并将\(a\)分成\((n+1)/2\)个数对,求最小的所有数对差的 ...

  5. c++ 向上取整和向下取整

    在c++ 中: ceil()表示向上取整 floor()表示向下取整 当然,这很显然对浮点数很好用. 但如果两个int类型的数想要向上取整呢? 我们用 (n-1)/m+1 来表示即可.

  6. 一文带你认识Docker

    Docker是一个容器技术的应用,而底层是由于Linux容器实现的,Docker只是实现层. 一.Linux容器 1.隔离与共享 一台服务器运行着多个逻辑隔离的服务器进程,谁的运行环境都不希望影响到谁 ...

  7. Linunx系统引导过程及MBR/GRUB故障

    Linunx系统引导过程 系统初始化进程 init进程 Systemd Systemd单元类型 允许级别所对应的systemd目标 修复MBR扇区故障 解决思路 操作 修复GRUB引导故障 解决思路 ...

  8. ELK Stack 介绍 & Logstash 日志收集

    ELK Stack 组成 Software Description Function E:Elasticsearch Java 程序 存储,查询日志 L:Logstash Java 程序 收集.过滤日 ...

  9. JSON简单理解

    JSON 与 JS 对象的关系 很多人搞不清楚 JSON 和 Js 对象的关系,甚至连谁是谁都不清楚.其实,可以这么理解: JSON 是 JS 对象的字符串表示法,它使用文本表示一个 JS 对象的信息 ...

  10. HDU 3949 XOR （线性基第k小）题解

    题意: 给出\(n\)个数,求出子集异或第\(k\)小的值,不存在输出-1. 思路: 先用线性基存所有的子集,然后对线性基每一位进行消元,保证只有\(d[i]\)的\(i\)位存在1,那么这样变成了一 ...