Flask Rest API 版本控制 - 返回的 URL

Question

FooBar Api 已发布

假设有一个开发团队正在开发一个名为 FooBar api 的 API，并带有几个端点：

GET /foo
    # returns {'bar': '/bar', 'data': 'foo'}

GET /bar
    # returns {'data': 'hello world!'}

现在，假设FooBar api 爆发并变得非常流行。来自世界各地的开发人员都在使用FooBar api，现在成千上万的项目完全依赖它。

---

问题

FooBar api 最近有了新的项目经理。他说，现在希望响应返回 message 而不是 data，因为 message “更具描述性”。不幸的是，对FooBar API 的任何更改都可能破坏数以千计的此类项目。尽管所有这些项目被破坏的开发人员大多会耐心并理解变化，FooBar 团队不想破坏他们自己的依赖项目并决定最好保持 api 向后兼容。

---

解决方案

FooBar api 需要进行版本控制。不幸的是there is no good way to do this。幸运的是FooBar 团队，他们的项目经理最了解并决定应该通过在 url 中放置版本号来完成版本控制，因为“这是他可以看到的部分”。因此，一旦FooBar api 的第二个版本完成，这两个版本应该如下所示：

FooBar v1
GET /foo
    # returns {'bar': '/bar', 'data': 'foo'}

GET /bar
    # returns {'data': 'hello world!'}

FooBar v2
GET /v2/foo
    # returns {'bar': '<url to bar>', 'message': 'foo'}

GET /v2/bar
    # returns {'message': 'hello world!'}

---

第二个问题

FooBar 团队现在有另一个问题；他们不知道<url to bar> 应该写什么。在几乎无限可能的字符排列中，他们令人印象深刻地能够将其归结为两个选择 - /v2/bar 和 /bar。

---

问题

使用/v2/bar 和/bar 的优缺点是什么？

Answer 1

两者都不做。具有不同 URL 的同一资源的两种不同表示形式与 REST 或 HTTP 不一致。它们是相同的资源，它们应该具有相同的 URL。

无论客户端使用 API 版本 1 还是 API 版本 2，他们仍然引用同一个资源，他们只是想要它的不同表示。因此，完全摆脱 URL 中的/v2/，让您的客户要求他们提供他们想要的版本作为媒体类型参数：

GET /foo HTTP/1.1
Accept: application/vnd.whatever+json;version=2
Connection: close

您现有的客户端不会提供版本参数，您可以默认使用版本 1。支持 API 版本 2 的新客户端将知道请求该资源的版本 2 表示。无论客户端使用哪个版本的 API，您的链接都可以正确引用相同的资源。