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

Question

我正在寻找在ASP.NET MVC 3中开发应用程序,并希望同时提供一个公共API.

从四处看看,似乎有两种方法可以实现.创建一个API区域并拥有返回json/xml的控制器.或者使用动作过滤器和单个前端控制器集,并根据请求标头返回json/xml/html.

我想稍后再做,但是我想知道如果你走这条路线你怎么能开始对api进行版本化？

如果你走第一条路线,你可以很容易地创建一个v1/v2控制器,但如果你这样做,你怎么能对它进行版本化？

Answer 1

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

1. 网址.在这种情况下,假设https://api.example.com/v1/projects与http://api.example.com/v2/projects不同,即使不是这种情况.Basecamp似乎这样做了.遵循这种方法,假设您始终必须支持旧的API.
2. 标题.URL保持不变,但是,客户端传递额外的HTTP标头,例如X-MYAPI-VERSION,每个请求都带有一个标识要使用的API版本的值.在谷歌文档列表API做到这一点.这种方法的一个潜在问题是HTTP头可能被客户端和服务器之间的中介剥离.
3. 参数.要绕过选项2的问题,您可以传递API版本以用作参数(例如https://api.example.com/projects?v=3).
4. 媒体类型.这里您的URL保持不变,但是,用户需要使用accept和content类型标头指定资源的表示.例如,可以使用"application/vnd.mycompany.resource [-version] [+ format]"呈现"项目",为v1 json提供"application/vnd.mycompany.project-v1 + json"的表示或" application/vnd.mycompany.project-v1 + xml"for v1 xml.当您需要新版本的项目时,mime类型可能如下所示"application/vnd.mycompany.project-v2 + xml".Github似乎支持这一点.
5. 部分有效载荷.在这种情况下,请求的有效负载包含要使用的版本号.例如,传递XML时,您可以查看命名空间以确定正在使用的API版本.对于JSON,您可以使用"$ version"或"_version"属性来指定版本.
6. 客户密钥.注册应用程序时,它指定要使用的API版本.验证客户端时,确保模拟其要使用的版本.
7. 没有明确的版本控制总是可以选择不对API进行版本控制,并尝试通过使所有字段都可选而透明地处理更改,并在缺少时适当地处理它们.您无论如何都可能会这样做,以使您的API的未来版本与您当前开发的版本兼容.

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

Answer 2

您可以采用两种路线之一 - 您可以在路线中包含 API（而不是http://app.lication/category/1类似的内容http://app.lication/api/v1/category/1），或者您可以包含自定义 HTTP 标头。

两者都可以让您区分正在调用哪个版本。