对于API向后兼容的最佳实践 [英] Best practices for API backwards compatibility

问题描述

我工作的一个iPhone / iPad的/ Android的应用程序，它用JSON API通信。

I'm working on an iPhone/iPad/Android app which communicates with a JSON API.

的应用程序的版本，第一个版本是完整的，现在发展的附加的阶段正在发生。在附加的阶段，应用程序需要与API的新版本集成，允许附加功能，如新屏幕或现有的屏幕中修改行为的用户访问。该应用程序确实需要但与API的previous版本向后。

The first release of the version of the app is complete, and now additional phases of development are taking place. In the additional phases, the app needs to integrate with a new version of the API and allow the user access to additional features such as new screens or modified behaviour within existing screens. The app does however need to be backwards with previous versions of the API.

什么是解决这一需求的最佳做法是什么？
我可以的可以在整个code做检查：

What is the best practice for tackling such a requirement? I could of could do checks throughout the code:

if (APIVersion == 1) {

} else if (APIVersion == 2) {

} else if (APIVersion == ....) {

}...

不过，我担心这种方法的可扩展性。
该工厂方法浮现在脑海，但我不知道，这到底会得到我的。

But I'm concerned about the scalability of this approach. The factory method comes to mind but I'm not sure how far this would get me.

谢谢，
马克

推荐答案

新REST API版本发布是一个非常罕见的事情。通常你可以通过添加新的可选参数或新方法实现向后兼容。例如，如果你有方法命名为搜索，但现在你不满意它的工作方式，你可以通过各种方式处理这个问题：

Release of a new REST API version is a very rare thing. Usually you can achieve backward-compatibility just by adding new optional parameters or new methods. For example, if you had method named search, but now you are dissatisfied with the way it works, you may deal with it in various ways:

• 如果变化是简单的，你可以添加一个新的模式参数默认为模式1 （所以它的后向兼容）。如果用户提供模式2 你有一个适当的如果状态检测到它，你提出你自己。


• 如果变化是一个大的，您可以添加它使用新界面新的搜索2 服务。然后您标记搜索方法pcated德$ P $（但仍然工作和向后兼容）。通常当你这样做，你可以重构您的code以这样的方式，几乎所有的逻辑是搜索2 方法中和旧的搜索的方法调用搜索2 内部与修改的参数（并重新格式结果正确）。如果你这样做正确，你永远不会需要改变搜索方法了。当你改变你的表等等 - 你只需要修改搜索2
。

• If the change is simple you may add a new mode parameter which defaults to mode1 (so it's backward-compatible). If user supplies mode2 you detect it with a proper if condition as you proposed yourself.
• If the change is a big one, you may add a new search2 service which uses the new interface. Then you mark search method as deprecated (but still working and backward-compatible). Usually when you do this, you can refactor your code in such a way, that almost all of the logic is inside the search2 method, and your old search method calls search2 internally with modified parameters (and re-formats the results appropriately). If you do this properly, you won't ever need to change search method anymore. When you alter your tables etc. - you will only need to modify search2.

我的观点是，避免释放 N + 1 -st一个REST API的版本。这样大放意味着所有的你的方法，而不仅仅是一个重大变化。许多主要的REST API的从未公布他们的API第2版，他们仍然使用版本1，只要稍微修改其中的部分，如上面的例子。

My point is, avoid releasing N+1-st version of a REST API. Such big release implies major changes in ALL of your methods, not just one. Many major REST APIs never released version 2 of their API, they still use version 1, just slightly modify portions of it, as in the example above.

如果你的绝对肯定关于发布 N + 1 -st你的API版本，所有创造新的切入点你的方法。如果你有一个名为服务文件夹中创建一个名为新的服务-V2 。重构你的服务 code，以便它使用最服务-V2 的。如果你认为这是矫枉过正，那么我认为你不需要 N + 1 -st您的API版本呢。

If you are absolutely sure about releasing N+1-st version of you API, create new entry points for ALL of your methods. If you had a folder named services, create new one named services-v2. Refactor your services code so that it uses the most of services-v2. If you think it's overkill, then I think you don't need N+1-st version of your API yet.

顺便说一句，不要混淆集中的API（如谷歌地图）和分布式的人（如Android）。 Android的发布新版本的API的时候，因为有Android的服务器milions（每个Android设备就是其中之一），他们都不能简单地通过远程升级谷歌。 Android的下一个版本仍与previous一个向后兼容，这个数字仅增加，表明新的功能。 Android的应用程序开发商为了形容最低要求使用这些号码为他们的应用程序。 然而，集中式的API通常会增加其版本号来表示一个主要的后向兼容的变化

BTW, do not confuse centralized APIs (like Google Maps) with distributed ones (like Android). Android releases new API versions all the time, because there are milions of Android servers (each Android device is one), and they all cannot be simply upgraded remotely by Google. The next version of Android is still backward-compatible with the previous one, the number is increased only to indicate new features. Android-apps developers use these numbers in order to describe "minimum requirements" for their apps. Whereas, centralized APIs usually increase their version number to indicate a major backward-incompatible change.

这篇关于对于API向后兼容的最佳实践的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！