api version最佳实践

最新推荐文章于 2024-03-18 09:56:49 发布

Mr.QingBin

最新推荐文章于 2024-03-18 09:56:49 发布

阅读量949

点赞数

分类专栏： android 跨门槛文章标签： android 网络

android 跨门槛专栏收录该内容

18 篇文章 0 订阅

订阅专栏

原文链接：http://stackoverflow.com/questions/389169/best-practices-for-API-versioning#

这是一个很好的问题。 URI设计的主题同时是REST API的最突出部分，因此，对该API用户的潜在长期承诺。

因为应用程序的演进，api的设计更像一个复杂的工程，编程语言，一样具有较少的可扩展性。URI设计应该有更少的自然约束，它应该保存随着时间的推移。应用程序和API的使用寿命越长，对应用程序和API的用户的承诺就越大。

另一方面，另一个事实是，很难预见将通过API消费的所有资源及其方面。幸运的是，没有必要设计做太多的超前设计。正确地定义每个资源和资源实例的所有资源端点和寻址方案就是一种正确的做法。

随着时间的推移，您可能需要向每个特定资源添加新资源和新属性，但是一旦资源寻址方案变为公开并因此最终，API用户访问特定资源的方法不应该更改。

此方法适用于早期API版本中支持的HTTP动词语义（例如PUT应始终更新/替换）和HTTP状态代码（它们应继续工作，以便在没有人工干预的情况下工作的API客户端应能继续工作像那样）。

此外，由于将API版本嵌入到URI中将通过具有随时间改变的资源地址/ URI而破坏作为应用状态的引擎（在Roy T.Fieldings博士论文中陈述）的超媒体的概念，我将得出结论，API版本不应该在资源URI中保存很长时间，这意味着API用户可以依赖的资源URI应该是永久链接。

从API用户观点，它是更容易使用和绑定到一个特定的API版本，当这是明显的，但只有有限的时间，即在开发过程中。

从API维护者的观点，通过使用主要处理文件作为（源代码）版本化的最小单位的源控制系统，更容易并行地维护不同的API版本。

然而，对于在URI中清晰可见的API版本，有一点需要注意：可能还会对此方法进行对象，因为API历史在URI设计中变得明显可见，因此容易随时间发生变化，这违背了REST准则。我认为！

绕过这个问题的合理方法是在无版本的API基本URI下实现最新的API版本。在这种情况下，API客户端开发人员可以选择：

1 ) 针对最新的api进行开发

2）绑定到特定版本的API（显而易见），但只在有限的时间

例如，如果API v3.0是最新的API版本，以下两个应该是别名（即对所有API请求的行为相同）：

http：// shonzilla / api / customers / 1234
http：//shonzilla/api/v3.0/customers/1234
http：// shonzilla / api / v3 / customers / 1234

此外，仍然尝试指向旧API的API客户端应该被通知使用最新的以前的API版本，如果他们使用的API版本已过时或不再支持。所以访问任何过时的URI，像这样：

http：//shonzilla/api/v2.2/customers/1234
http：//shonzilla/api/v2.0/customers/1234
http：// shonzilla / api / v2 / customers / 1234
http：//shonzilla/api/v1.1/customers/1234
http：// shonzilla / api / v1 / customers / 1234

应返回任何指示重定向的30x HTTP状态代码，这些代码与Location HTTP标头结合使用，重定向到相应的资源URI版本，这些资源URI仍然是这一个：

http：// shonzilla / api / customers / 1234

有至少两个重定向HTTP状态代码适用于API版本控制场景：

-301永久移动，表示具有请求的URI的资源被永久移动到另一个URI（它应该是不包含API版本信息的资源实例永久链接）。此状态代码可用于指示过时/不受支持的API版本，通知API客户端版本化资源URI已由资源固定链接替换。
-302找到，指示所请求的资源临时位于另一位置，而所请求的URI仍然可以被支持。当无版本URI暂时不可用并且使用重定向地址重复请求（例如指向嵌入了APi版本的URI）时，此状态代码可能很有用，我们想告诉客户端继续使用它（即，固定链接）。
其他情况可以在HTTP 1.1的Redirection 3xx章节中找到

对于android应用开发来说：

将version放到url中也不是一个好的选择，通常我们传递参数使用json的形式。一般会将version放到request param基类中。

而服务端会将解析json中的参数，来适配到具体的后台接口中去