ASP.NET MVC 应用程序的版本控制 REST API [英] Versioning REST API of an ASP.NET MVC application

问题描述

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

I'm looking at developing an application in ASP.NET MVC 3 and would like to provide a public API at the same time.

环顾四周，似乎有两种方法可以解决.创建一个 API 区域并具有返回 json/xml 的控制器.或者使用动作过滤器和一组前端控制器，并根据请求标头让它们返回 json/xml/html.

From looking around, there seems to be 2 ways to go about it. Either create an API area and have controllers that return json / xml. Or use action filters and a single front end set of controllers, and have those return json / xml / html depending on the request headers.

我想稍后再做，但我想知道如果你走这条路，你如何对你的 api 进行版本控制?

I'd like to do the later, but I was wondering how you could go about versioning your api if you went this route?

如果您采用第一条路线，您可以轻松地创建一个 v1/v2 控制器，但如果您选择后者，您如何对其进行版本控制?

If you go the first route, you could easily just create a v1 / v2 controller, but if you do the later, how could you version it?

推荐答案

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

Versioning is a rather complex issue to begin with. Here are ways I looked at before:

1. 网址.在这种情况下，https://api.example.com/v1/projects 被假定为与 http://api.example.com/v2/projects，即使情况并非如此.Basecamp 似乎做到了这一点.按照这种方法，假设您将始终必须支持旧的 API.
2. 标题.URL 保持不变，但是，客户端传递一个额外的 HTTP 标头，比如 X-MYAPI-VERSION，每个请求都带有一个标识要使用的 API 版本的值.Google 文档列表 API 执行此操作.这种方法的一个潜在问题是客户端和服务器之间的中介可能会剥离 HTTP 标头.
3. 参数.为了规避选项 2 的问题，您可以传递 API 版本以用作参数(例如 https://api.example.com/projects?v=3">https://api.example.com/projects?v=3">example.com/projects?v=3).
4. 媒体类型.这里您的 URL 保持不变，但是，用户需要使用接受和内容类型标头指定资源的表示形式.例如，可以使用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 时，您可以查看命名空间以确定正在使用的 API 版本.对于 JSON，您可以使用$version"或_version"属性来指定版本.
6. 客户端密钥.注册应用程序时，它指定要使用的 API 版本.当您对客户端进行身份验证时，您确保模拟它想要使用的版本.
7. 无显式版本控制 始终可以选择不对 API 进行版本控制，并尝试透明地处理更改，方法是将所有字段设为可选字段，并在缺失时进行适当处理.无论如何，您都可能会这样做，以使您的 API 的未来版本与您今天正在开发的版本兼容.

1. URL. In this case https://api.example.com/v1/projects is assumed to be a different resource than http://api.example.com/v2/projects, even though its not the case. Basecamp seems to do this. Following this approach, assume you'll always have to support old APIs.
2. Headers. The URLs remains the same, however, the client pass an additional HTTP header, say X-MYAPI-VERSION with each request with a value identifying the version of the API to use. The Google Documents List API do this. A potential problem with this approach is that HTTP headers may be stripped by intermediaries between the client and server.
3. Parameters. To circumvent the problem with option 2, you can pass the API version to use as a parameter (such as https://api.example.com/projects?v=3).
4. Media types. Here your URLs stay the same, however, users are required to specify the representation of the resources using the accept and content type headers. For example, a "project" can be presented using "application/vnd.mycompany.resource[-version][+format]" giving your representations of "application/vnd.mycompany.project-v1+json" for v1 json or "application/vnd.mycompany.project-v1+xml" for v1 xml. When you need a new version of a project comes along the mime type may look as follows "application/vnd.mycompany.project-v2+xml". Github seems to support that.
5. Part of payload. In this case the payload of the request contains the version number to use. For example, when XML is passed, you can look at the namespace to determine which version of the API is being used. For JSON, you can use a "$version" or "_version" property to specify the version.
6. Client Key. When the application is registered, it specifies which version of the API it wants to use. When you authenticate the client, you ensure that you emulate the version it wants to use.
7. No explicit versioning There is always the option not to version your API and try to handle changes transparently by making all fields optional and handle them appropriately when they are missing. Chances are you will be doing this anyways to make future versions of your API compatible with the version you are developing today.

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

Many recommend option 4, although its not always practical. Most of these options require additional work to get working with ASP.NET MVC.

这篇关于ASP.NET MVC 应用程序的版本控制 REST API的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！