api版本控制_API版本控制

api版本控制

So, you are new to this team. And in one of the bi-weekly tech leads’ meetings, one thing leads to another and you casually bring up how the error messages on all the APIs are not consistent. You hear one of the engineers telling you that their pull requests to update the core error handler have always been kept on hold and have never been merged. Before you could ask for more information, you hear a few other audible nods. All those have one thing in common, they are all breaking changes. Breaking, for the downstream systems and/or breaking for the clients that consume these resources. This discussion makes way for one of the commonly contested aspects of API development: “versioning”.

因此，您是这个团队的新手。 在每两周一次的技术负责人会议中，一件事导致另一件事，而您随便提出了所有API上的错误消息是如何不一致的。 您会听到其中一位工程师告诉您，他们更新核心错误处理程序的请求一直处于暂停状态，并且从未合并。 在您请求更多信息之前，您会听到其他一些听得见的点头。 所有这些都有一个共同点，都是突破性的变化。 对于下游系统来说是中断，和/或对于消耗这些资源的客户端来说是中断。 该讨论为API开发中最受争议的方面之一让路：“ 版本控制” 。

I think the topic of API versioning is probably as old as or older than the topic of URL design for applications themselves. And probably a discussion that most teams involved in API development get involved in. What makes it more interesting is the fact that there is no right answer or approach that fits all use cases. And thus makes up for quite an interesting conversation.

我认为API版本控制的主题可能早于应用程序本身的URL设计主题。 可能是大多数参与API开发的团队都参与了讨论。更有趣的是，没有适合所有用例的正确答案或方法。 因此弥补了一个非常有趣的对话。

Why would you need to version your APIs?A versioning strategy allows clients to continue using the existing API and migrate their applications to the newer API when they are ready. If you need to make breaking changes you might continue to do so and migrate to this new structure only when all the essential stakeholders are ready for it.

为什么需要对API进行版本控制？ 版本控制策略允许客户端继续使用现有的API，并在准备就绪时将其应用程序迁移到较新的API。 如果您需要进行重大更改，则可以继续这样做，并且仅在所有重要的利益相关者都准备好进行迁移时，才迁移到该新结构。

While certain modifications like adding new routes or route parameters shouldn’t cause any problems. Changes that could affect existing clients or downstream systems that consume your API would mean that you would need to think about a strategy for versioning thoroughly. Like most cases, we have multiple ways to approach this.

尽管某些修改(例如添加新路由或路由参数)不会引起任何问题。 可能影响使用您的API的现有客户端或下游系统的更改将意味着您需要彻底考虑版本控制策略。 与大多数情况一样，我们有多种方法可以解决此问题。

“The most RESTful approach to versioning an API is to not version it at all.”

“对API进行版本控制的最RESTful方法是根本不对它进行版本控制。”

~(Old Asgardian Proverb)

〜(古阿斯加德谚语)

Embedding API version in the URI?This looks like the easiest way forward. However, this would be against the HATEOAS constraint [Hypermedia As The Engine Of Application State]. Adding a version number to the API would mean that the client is making an assumption of how an API would behave and would thus mean that the API is no longer opaque. If we go by the book, clients should be dynamic and only rely on the API responses [see. web browsers]. It might also mean that incrementing the API version would translate into branching the entire API resource.

在URI中嵌入API版本？ 这看起来是最简单的方法。 但是，这将违反HATEOAS约束[ 超媒体作为应用程序状态的引擎 ]。 向API添加版本号将意味着客户端正在假设API的行为方式，因此将意味着该API不再是不透明的。 如果我们按书进行，客户端应该是动态的，并且仅依赖于API响应[ 请参见。 网络浏览器]。 这也可能意味着增加API版本将转化为分支整个API资源。

GET https://www.sampleresource.com/v1/foo

Through content negotiationUsing the content negotiation strategy. This helps us by requiring only a single resource to represent the API instead or versioning the entire API and thus giving us more control over versioning. Also, we would not need to define custom routing rules, like we had to while using version as part of the URI path.

通过内容协商使用内容协商策略。 通过仅需要一个资源来表示API或对整个API进行版本控制，这将为我们提供帮助，从而使我们可以更好地控制版本。 而且，我们不需要定义自定义路由规则，就像我们在将版本用作URI路径的一部分时必须定义的那样。

GET /foo
Accept: application/ion+json;v2.0

Query ParametersThis approach is very straightforward and is also easy to set defaults to the latest version in case of missing query parameters.

查询参数这种方法非常简单，而且在缺少查询参数的情况下也很容易将默认值设置为最新版本。

www.sampleresource.com/api/foo?version=1

Biggest challenge with this approach would be setting up routing.

这种方法最大的挑战是设置路由。

Custom HeadersThis is another approach which might not be very popular with teams, but does the job. Sending version number as a custom header.

自定义标题这是另一种方法，在团队中可能不是很流行，但是可以胜任。 发送版本号作为自定义标头。

curl -H “accepts-version: 1.0”www.sampleresource.com/api/foo

Lets talk code.net core like few other popular frameworks, offers versioning through content negotiation via custom libraries.

像其他一些流行的框架一样， 让我们谈论代码 .net核心， 通过自定义库通过内容协商提供版本控制。

Add the nuget package ‘Microsoft.AspNetCore.Mvc.Versioning’ and update the startup.cs accordingly.

添加nuget包' Microsoft.AspNetCore.Mvc.Versioning'并相应地更新startup.cs 。

public void ConfigureServices(IServiceCollection services)
{
    services.AddApiVersioning(options =>
    {
        // if we don't specify an api version, assume the default versioon is 1.0
        options.DefaultApiVersion = new ApiVersion(1, 0);
        
        // specify where to read the version number from
        options.ApiVersionReader
            = new MediaTypeApiVersionReader();
        
        // if api version is not specified assume default version to be the one we specified earlier
        options.AssumeDefaultVersionWhenUnspecified = true;
        
        // so that we can get an api version information in the responses
        options.ReportApiVersions = true;
        options.ApiVersionSelector
             = new CurrentImplementationApiVersionSelector(options);
    });
}

We can then go ahead and add a class level attribute of ‘ApiVersion’ on our BaseController.

然后，我们可以继续在BaseController上添加类级别属性“ ApiVersion ”。

namespace demoApi.Controllers
{
  [Route("/")]
  [ApiController]
  [ApiVersion("1.0")]
  public class BaseController: ControllerBase
  {
  public IActionResult foo()
  {
    // implementation
  }
  }
}

Now when you compile and send a request to this endpoint. You might notice a change in the headers. Something like this:

现在，当您编译并向该端点发送请求时。 您可能会注意到标题中的更改。 像这样：

api-supported-versions -> 1.0

Just for kicks if you send in a different header. Like this:

如果您发送其他标头，则仅用于踢球。 像这样：

curl -i -H "Accept: application/json;v=2.0" 
http://www.sampleresource.com/api/foo

You might notice that the same call might throw a ‘400 Bad request’, stating that the error code as ‘UnsupportedApiVersion’ . We don’t have an apiversion attribute corresponding to version 2.0 on this endpoint. But if we did, we would have been able to request that.

您可能会注意到，同一调用可能会引发“ 400错误的请求 ”，并指出错误代码为“ UnsupportedApiVersion ”。 在此端点上，我们没有与版本2.0相对应的apiversion属性。 但是，如果我们做到了，我们将能够提出要求。

Which versioning strategy to use?Which approach to use depends on the project and the intent. Do you want versioning that’s more explicit to clients or one that is more flexible and clean? Are you expecting the interface to be stable or have breaking changes? Planning and thinking through all the use cases for your API in advance can reduce the need to make breaking changes down the road.

使用哪种版本控制策略？ 使用哪种方法取决于项目和意图。 您是否想要对客户端更明确的版本控制，还是更灵活，更干净的版本控制？ 您是否希望界面稳定或有重大更改？ 预先计划和考虑API的所有用例，可以减少在未来进行重大更改的需求。

翻译自: https://medium.com/@karthikkottugumada/api-versioning-7f6f713c6b14

api版本控制