c# - ASP.NET MVC 应用程序的版本控制 REST API

Question

我正在考虑在 ASP.NET MVC 3 中开发一个应用程序，并希望同时提供一个公共(public) API。

环顾四周，似乎有两种方法可以解决这个问题。创建一个 API 区域并拥有返回 json/xml 的 Controller 。或者使用操作过滤器和一组前端 Controller ，并根据请求 header 让它们返回 json/xml/html。

我想稍后做，但我想知道如果你走这条路，你怎么能对你的 api 进行版本控制？

如果您采用第一种方式，您可以轻松地创建一个 v1/v2 Controller ，但如果采用第二种方式，您如何对其进行版本控制？

Answer 1

版本控制从一开始就是一个相当复杂的问题。以下是我之前看过的方法:

1. 网址。在这种情况下 https://api.example.com/v1/projects假定为与 http://api.example.com/v2/projects 不同的资源，尽管事实并非如此。 Basecamp似乎是这样做的。按照这种方法，假设您将始终必须支持旧 API。
2. 标题。 URL 保持不变，但是，客户端传递一个额外的 HTTP header ，例如 X-MYAPI-VERSION，每个请求都有一个标识要使用的 API 版本的值。 Google Documents List API做这个。这种方法的一个潜在问题是 HTTP header 可能会被客户端和服务器之间的中介剥离。
3. 参数。要避免选项 2 的问题，您可以传递 API 版本以用作参数(例如 https://api.example.com/projects?v=3 )。
4. 媒体类型。此处您的 URL 保持不变，但是，用户需要使用接受和内容类型 header 指定资源的表示形式。例如，可以使用“application/vnd.mycompany.resource[-version][+format]”来呈现“项目”，为 v1 json 或“application/vnd.mycompany.project-v1+xml”用于 v1 xml。当您需要项目的新版本时，mime 类型可能如下所示“application/vnd.mycompany.project-v2+xml”。 Github似乎支持这一点。
5. 有效载荷的一部分。在这种情况下，请求的有效负载包含要使用的版本号。例如，当传递 XML 时，您可以查看 namespace 以确定正在使用的 API 版本。对于 JSON，您可以使用“$version”或“_version”属性来指定版本。
6. 客户端 key 。注册应用程序时，它会指定要使用的 API 版本。当您验证客户端时，您确保您模拟它想要使用的版本。
7. 没有明确的版本控制 始终可以选择不对您的 API 进行版本控制，并尝试透明地处理更改，方法是将所有字段设为可选，并在缺少时适本地处理它们。无论如何，您很可能会这样做，以使您的 API 的 future 版本与您今天开发的版本兼容。

许多人推荐选项 4，尽管它并不总是实用。这些选项中的大多数都需要额外的工作才能使用 ASP.NET MVC。