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.

环视，似乎有2种方式去了解它。无论是创建一个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 的被假定为比<一个不同的资源HREF =htt​​p://api.example.com/v2/projects> http://api.example.com/v2/projects 时，即使它的情况并非如此。 大本营似乎做到这一点。按照这一办法，假设你永远要支持旧的API。


2. 标题即可。网址是一样的，但是，客户端通过一个附加的HTTP头，说的X MYAPI-VERSION与标识使用API​​的版本值的每个请求。该谷歌文档列表API 做到这一点。这种方法的一个潜在问题是，HTTP头可以由客户端和服务器之间的中介被剥离。


3. 参数即可。为了规避与选项2的问题，可以作为参数传递（如 HTTPS使用API​​的版本：// API。 example.com/projects?v=3 ）。


4. 媒体类型即可。在这里，你的URL保持不变，但是，用户需要使用指定的接受和内容类型头资源的重新presentation。例如，一个项目可以是presented使用应用程序/ vnd.mycompany.resource [-version] [+格式]给予应用程序/ vnd.mycompany.project-V1 +您重新presentations JSON为V1 JSON或应用程序/ vnd.mycompany.project-V1 + XML的第一版XML。当你需要一个项目的新版本一起MIME类型可能会是这样的application / vnd.mycompany.project-V2 + XML的由来。 Github上似乎支持。


5. 负载的一部分。在这种情况下，请求的有效载荷包含要使用的版本号。例如，当XML传递，你可以看看命名空间，以确定正在使用哪个版本的API。对于JSON，你可以用一个$版或_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屋！