如何解决与 API 版本相关的障碍

Question

我正在使用一项 restfull 服务，并且有 20 多个客户正在使用该服务。

@Path("/provider")
public class Provider{

@Path("/simpleprovider")
@GET
public String getProvider(){
return "Simple Provider";
}
}

现在我决定推出服务版本，我有很多谷歌，阅读我的文章但我完全困惑我该怎么办？假设我为@Path("/provider/v1") 之类的新服务更改URI，而不是我应该如何为现有客户提供支持？考虑到这件事，每当 api 新版本生效时，我是否必须为每个客户端提供更改？

谷歌搜索后，我发现有 3 种方法可以提供版本控制

1. URL 版本控制

2. 自定义请求标头

3. 内容类型

但找不到任何实际的例子，请在这方面帮助我

http://stackoverflow.com/questions/389169/best-practices-for-api-versioning http://www.narwhl.com/2015/03/the-ultimate-solution-to-versioning-rest-apis-content-negotiation/ http://restcookbook.com/Basics/versioning/

http://www.troyhunt.com/2014/02/your-api-versioning-is-wrong-which-is.html

http://www.lexicalscope.com/blog/2012/03/12/how-are-rest-apis-versioned/

任何帮助将不胜感激

Answer 1

对服务进行版本控制可能非常棘手，并且在确定版本控制策略时始终是一个重大决定。特别是如果您有人使用该服务。根据我的经验，有几点需要考虑：

1. 了解并沟通何时以及是否计划使用 API 的日落版本。您最不想遇到的问题是您必须维护 10 个不同版本的 API。

2. 了解版本更改是否是绝对必要的。一个好的经验法则是核心功能是否正在发生变化，或者合同是否可能破坏与您的 API 集成的某人的软件。在确定是否真的需要版本时，需要考虑以下几点：

   • 如果您要从资源中删除字段。
   • 如果您要删除（或更新）一个 URL（或方法）。
   • 如果现有端点（或方法）逻辑将发生变化，需要消费者重新实现。
   • 总体而言，如果您所做的更改会破坏某人与您的 API 的集成。

3. 您是否需要进行与以前版本不向后兼容的数据库更改？这是版本控制变得非常有趣（讽刺地）的时候，因为现在您可能必须使您的数据库向后兼容，根据我的经验，这可能是一个难以处理的问题。

不过，为了回答您的问题，我找到了在 URL 中进行版本的最佳方式。版本控制要非常简单和深思熟虑，以便您的集成商一目了然。例如：

• GET /v1/products/{id} // 版本 1
• GET /v2/products/{id} // 版本 2

** 如果您决定使用 URL 版本控制，那么我的建议是为版本添加“v”和一个单一的数字，例如 1 或 2。不要进入版本、子版本等...这将使您的API 似乎变化很大，这可能会引起消费者的关注。此外，尽可能将版本保持在 URL 的最左侧。这个想法是版本右侧的所有内容都是新的版本化资源。 我会避免使用标头对您的服务进行版本控制。您不想对消费者隐藏版本。尽可能对版本控制保持透明和明确。

URL 中的版本控制还允许您在 Web 服务器和代理上执行一些有用的路由和操作。您可以在实际代码中使用这样的版本，例如：

[HttpGet("v1/products")]
public Product GetProduct(string id)
{
    return _repository.GetProduct(id);
}

或者您可以通过设置虚拟目录（或其他）来使用您的 Web 服务器进行版本控制。那么你的代码可能看起来像这样：

[HttpGet("products")]
public Product GetProduct(string id)
{
    return _repository.GetProduct(id);
}

无论您决定版本化，重要的是要考虑每个决定的优缺点并权衡它们，因为如果您正在运行一个人们正在使用错误决定的 API，那么您会很快赶上您。