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

Question

我有一个 restfull 服务，有超过 20 个客户正在使用这个服务。

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

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

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

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

URL 版本控制
自定义请求header
内容类型

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

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

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

了解并沟通何时以及是否计划使用 API 的日落版本。您最不想遇到的问题是您必须维护 API.
了解是否绝对有必要进行版本更改。一个好的经验法则是核心功能是否发生变化，或者合同是否可能破坏与您的 API 集成的某人的软件。在确定您是否真的需要版本时，需要考虑以下几点：
- 如果您要从资源中删除字段。
- 如果您要删除（或更新）URL（或方法）。
- 如果现有端点（或方法）逻辑将发生变化，需要消费者 re-implement。
- 总的来说，如果您所做的更改会破坏与您的 API 集成的人。
您是否需要进行与您之前版本不向后兼容的数据库更改？这是版本控制变得非常有趣（讽刺地）的时候，因为现在您可能必须使您的数据库向后兼容，根据我的经验，这可能是一个很难处理的问题。

不过，为了回答您的问题，我发现最好的版本是在 URL 中。版本控制要非常简单和深思熟虑，以便 crystal 对您的集成商来说是清楚的。例如：

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

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

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

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

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

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

无论您决定版本如何，考虑每个决定的利弊并权衡它们是非常重要的，因为如果您是运行一个 API 人们正在使用错误的决定赶快赶上你。

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

How to solve obstacles related to API version

java

api

restful-architecture

api-versioning