ASP.NET MVC 3 REST API Versions Best Practices

Question

I am wondering if there is a practice of creating a REST API with ASP.NET MVC 3? I'm currently thinking of creating a controller for each version of the REST API. For example, so far I have:

public class V1Controller : Controller { public V1Controller() { } public ActionResult GetUser(string userId, IUserRepository userRepostory) { //code to pull data and convert to JSON string return View("Results"); } public ActionResult GetUsersByGroup(string groupId, IUserRepository userRepostory) { //code to pull data and convert to JSON string return View("Results"); } } 

Then for the views, I overwrite _ViewStart.cshtml to remove the layout, and then I have Results.cshtml that just displays the data formatted in the controller action, right now JSON. Having every REST call in one controller seems too big, but this is the best way I can think so that I can maintain clean separate versions of the API, so when it comes to creating version 2 of the API, I can create a V2Controller and not break the existing API to give people time to switch to the new API.

Is there a better way to create a REST API with ASP.NET MVC 3?

Answer 1

I was able to find a decent solution using MVC areas.

First, I wanted my API to match this url. Definition:

 http://[website]/[major_version]_[minor_version]/{controller}/{action}/... 

I also wanted to split different versions in separate Project files and use the same controller names in each version:

 "../v1_0/Orders/ViewOrders/.." => "../v2_3/Orders/ViewOrders/.." 

I searched and found a workable solution using MVC scopes.

I created a new project in my solution called "Api.Controllers.v1_0" and, as a test, put the SystemController.cs file:

 using System.Web.Mvc; namespace Api.Controllers.v1_0 { public class SystemController : Controller { public ActionResult Index() { return new ContentResult() {Content = "VERSION 1.0"}; } } } 

Then I added the file v1_0AreaRegistration.cs :

 using System.Web.Mvc; namespace Api.Controllers.v1_0 { public class v1_0AreaRegistration : AreaRegistration { public override string AreaName { get{ return "v1_0";} } public override void RegisterArea(AreaRegistrationContext context) { context.MapRoute( "v1_0", "v1_0/{controller}/{action}/{id}", new { controller = "System", action = "Index", id = UrlParameter.Optional } ); } } } 

I went through the same steps above for the project "..v1_1" with the corresponding files there, added the projects as links to my MVC project "Api.Web" and was turned off and started.

Answer 2

If all you return is JSON, you don't need a view. Yusr Return

 new JsonResult(){Data = Data}; 

Take a look here .

---

Also, from the point of view of version control, versions can be implemented as different controllers or as additional methods in one controller. But, not knowing why you need versions and why your clients (which I believe are browsers) should know about version control, it is not clear from your question.

Answer 3

A controller, such as the one you placed in your code example, should always store the methods that you have, for example GetUsersByGroup() with the same signature. I do not see how there could be another version of this method.

The inputs are a group and a repository (which I think comes from DI). The result is a list of users in JSON format. This is all that matters to API users. What you do inside this method is not one business.

You should think more about inputs and outputs. You should not change the signatures of existing actions, if it is really necessary for this.

Think of the controller class in terms of interface implementation. You have an interface and a controller class - this is an implementation (I mean, you do not need to have this, but just think about it this way). You rarely change the interface as soon as one or more classes implement it. But you can add methods to it. And this requires only changes in the implementation of classes - this does not violate the functionality of the API, and everyone who uses it can continue to use it.