Project Oxford API URL中的新版本更改 [英] New Versioning Changes in Project Oxford API URLs

问题描述

我在12月18日的电子邮件中注意到，您已从"https：//api.projectoxford.ai/face/v {M} /"更改了网址中的API版本控制架构。到https://api.projectoxford.ai/face/v{M}.{m}/"其中{M}是主要版本，{m}是次要
版本。  我意识到您这样做是为了与其他Microsoft API URL方案（例如Microsoft Graph）更加一致。  但是，我不确定此更改是否有意义，因为API不应在次要版本
中进行任何重大更改（根据语义版本控制的规则）。   http：//semver.org/
$


基本上，如果API发生重大变化，主要版本号应该更改，因此客户端会需要指向一个新URL来调用新接口。  如果有不间断的更改（例如附加功能，
性能增强，错误修复等），那么次要版本号应该更改，主版本号应该保持不变，但是调用客户端不应该关心它所调用的次要版本（因为没有任何重大变化）。
 事实上，客户端（理论上）总是希望调用最新的次要版本来获得最新次要版本提供的任何性能优化，错误修复等。  因此，指定次要版本应该（理论上）不会优先于先前的URL架构
，并且（理论上）是不利的，因为调用客户端不再自动获得现有功能的不间断增强功能。 br />


此外，现在您需要托管，维护和支持API的每个次要版本，因为客户端将与这些次要版本（将具有更高版本）相关联费用给你）。  并且客户需要不断更新他们的URL到更高版本只需
，以获得次要功能添加，增强功能和错误修复（这将使调用客户的成本更高）。



至少，如果您计划创建指向API的特定主要次要版本的URL，那么保留一个仅指向最新版本的更通用的URL也许是有意义的。该主要版本的发布（例如"v1"将始终
指向1.x的最后一个版本），以便调用客户端可以选择他们需要的版本控制的粒度。  它还可以提供出色的反馈，了解用户更喜欢与您的API进行互动的方式，因为您可以快速计算每种网址风格的
唯一来电者的数量。



最后，如果这是一个随意的变化，我不确定这个变化对我有意义（基于我所解释的）并且我很想知道为什么其他的Microsoft API决定开始以这种方式构建其API URL。  如果您所做的更改有
令人信服的理由，请告诉我们，以便我更好地了解此更改的原因。  我很可能在我的假设中弄错了，这种构建URL的方式有一些优点，我不知道
。

I noticed in your email on Dec 18 that you've changed your API versioning schema in your URLs from "https://api.projectoxford.ai/face/v{M}/" to https://api.projectoxford.ai/face/v{M}.{m}/" where {M} is the major version and {m} is the minor version.  I realize that you're doing this to be more consistent with other Microsoft API URL schemes (e.g. Microsoft Graph).  However, I'm not certain that this change makes sense because APIs should not have any breaking changes in minor versions (according to the rules of semantic versioning).  http://semver.org/

Essentially, if there was a breaking change to the API, the major version number should change, and thus the client would need to point to a new URL to make calls to the new interface.  If there are non-breaking changes (e.g. additional functionality, performance enhancements, bug fixes, etc.) then the minor version number should change, the major version number should stay the same, but the calling client should not care which minor version it is calling (because there haven't been any breaking changes).  In fact, the client should (in theory) always want to call the latest minor version to get any performance optimizations, bug fixes, etc. that the latest minor version provides.  Thus, specifying the minor version should (in theory) offer no advantages over your previous URL schema and (in theory) be disadvantageous because the calling clients are no longer automatically getting non-breaking enhancements for existing features.

In addition, now you will need to host, maintain, and support every minor version of the API as clients will be tied to these minor versions (which will have a higher cost to you).  And clients will need to keep updating their URLs to later versions just to get minor feature additions, enhancements, and bug fixes (which will have a higher cost to the calling clients).

At minimum, if you are planning to create URLs to point to specific Major-minor versions of the API, maybe it would make sense to also keep around a more generic URL that only points to the latest release of that major version (e.g. "v1" will always point to the last version of 1.x) so that calling clients can choose the granularity of versioning that they need.  It would also provide excellent feedback as to which way users prefer to interact with your API as you could quickly count the number of unique callers to each style of URL.

Ultimately, if this was an arbitrary change, I'm not sure that the change makes sense to me (based on what I've explained) and I would be curious to know why the others Microsoft APIs decided to start structuring their API URLs this way.  If there is a compelling reason for the changes you've made, please let me know so that I can better understand the reason for this change.  It's quite likely I'm mistaken in my assumptions and there are advantages to this way of structuring URLs that I am unaware of.

推荐答案

马修，

感谢您提供反馈意见。您上周应该收到一封关于重大更改的电子邮件，此论坛中也发布了一条公告。

Thank you for the feedback. You should have a received an email about the breaking changes last week, there's also an announcement posted in this forum.

来自电子邮件：

如果您正在使用持久化数据，例如Person Group和Person对象的识别功能，然后您需要重新创建和训练这些对象。这是一次性更改，未来的API更新不会影响持久数据。

If you are using persisted data, such as the identification functionality with Person Group and Person objects, then you’ll need to recreate and train those objects. This is a one-time change and future API updates will not impact persisted data.

从v1.0开始，我们可以无缝地继续前进升级持久数据。没有引入新版本就没有办法做到这一点。我们利用这个机会也更新了命名。正如您所指出的，在大多数情况下，用户不会因为他们不会代表一个突破性的更改边界而需要担心次要版本，但在某些特定情况下，我们会根据具体情况使用它们基础，并始终努力清楚地记录和沟通，以及旧的
版本的退休计划。

Starting with v1.0 and moving forward we can seamlessly upgrade persisted data. There was not a way to do this without introducing a new version. We used the opportunity to also update the naming. As you pointed out, in the majority of cases users won't need to worry about the minor versions as they won't represent a breaking change boundary, but in some select cases we will use them on a case by case basis, and always strive to document and communicate out clearly, as well as the retirement plan for older versions.

我们可以利用次要版本更改的FaceAPIs的一个示例是面部检测模型的改进，其中输出格式保持不变但检测到更多面部。  while net我们可能会检测到更多的面孔，有些情况是
，旧模型检测到一张脸，但新模型没有。如果应用程序对此更改非常敏感，则依赖于次要版本将能够测试更改。此时，我们打算为Face
API带来的所有新功能都是兼容的，并且不需要进行重大改变。

One example for FaceAPIs where we may leverage minor version changes, would be an improvement in the face detection model, where the output format stays the same but more faces are detected. While net we may detect even more faces, there are some cases where the old model detected a face but the new one does not. If an application is incredibly sensitive to this change relying on minor versions would enable the testing of the change. At this point in time, all the new features we intend to bring to the Face APIs are compatible and will not necessitate a breaking major change.

我很欣赏那些不需要指定次要版本的复杂性的主要版本URL的建议，并将其放在我们的待办事项上并调查我们如何最好地支持所有的API。

I appreciate the suggestion on major version only URL for those that don't need the complexity of specifying the minor version and will put this on our backlog and investigate how best we could support this for all the APIs.

另请注意，在公开预览期间，我们将更加自由地进行更改。

Also note that during public preview we will be a bit more liberal in making changes.

这篇关于Project Oxford API URL中的新版本更改的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！