API版本管理中的沟通问题

转：

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