Saturday, March 31, 2012

REST Services with ASP.NET Web API

Sometimes back, ASP.NET MVC 4 beta was release, this comes with quite a lot of capabilities to create mobile web applications with HTML5, to new features on Razor etc..
One of the milestones of this release is ASP.NET Web APIs, which allows developers to implement REST services. .NET 3.5/4.0 WCF provides us with the support of creating REST APIs using the webHttpBinding, however most of the features required to run the service needs the ASP.NET compatibility mode, this basically means the request to the REST service would first go through the ASP.NET pipeline, before being handed over to WCF. Then there was the WCF Web API, where Microsoft tried to re-define how REST services are created, but they opted in for moving REST support into ASP.NET and then to WCF, hence ASP.NET Web API, becomes the de facto technology for creating REST services. WCF WebHttpBinding would still exist, bu the recommendation is to to use Web APIs.

Implementing a Web API is simple, the steps involved are...
1) Create a MVC 4 project
2) Define a route for web APIs
2) Create a controller but that inherits from ApiController instead of Controller
4) Start writing those GET, POST, PUT and DELETE methods....

Once you have installed ASP.Net MVC 4, you can create a controller like this...

public class ProjectsController : ApiController


public IList GetProjects()


return GetProjectsFromDB();


public void PostProject(Project project)





in your global file, you can create a route setting like this...


name: "DefaultApi",

routeTemplate: "api/{controller}/{id}",

defaults: new { id = RouteParameter.Optional }


That's it you can open up a web browser or fiddler and make request, to call the method GetProjects(), you URL would be like this http://localhost:8080/api/Product. In fiddler you would see the JSON response similar to this....

{"EndDate":"\/Date(1333251468665+0530)\/","ProjectID":1,"ProjectName":"XYZ 12","ProjectType":"T&M","StartDate":"\/Date(1333251468665+0530)\/"},{"EndDate":"\/Date(1333251468665+0530)\/","ProjectID":2,"ProjectName":"JJ 777","ProjectType":"FB","StartDate":"\/Date(1333251468665+0530)\/"}

Now, if you know MVC, you would be asking me, you did not refer the action in the URL or in the route table, so how does know to invoke the GetProducts()?. The answer is the controller check to see the HTTP method the request arrived on, if it is a GET, the controller will try to match any controller method that starts with the word GET. This is the same convention for POST. For an example , the PostProject() method can be invoked by a call to the URL format http://localhost:8080/api/Product. As long as you make the request as a POST method, the PostProject() method will be called. This convention allows the concept of a resource being governed by one controller by the HTTP verbs GET, POST, DELETE and PUT.

With the default convention discussed above, if you want to have method that does not start with the word Get or multiple methods with the same signature starting with the word GET, you would have to specify a route for this and explicitly specify the action part in the URL. You would also need to attribute the methods with either HttpGet, HttpPost etc...


public IList<Project> ActiveProjects()


return GetProjectsFromDB(true);


Your route settings in the global file would be...


name: "DefaultApiWithAction",

routeTemplate: "api/{controller}/{action}/{id}",

defaults: new { id = RouteParameter.Optional }

The URL format you would use to invoke this method would be


Unlike WCF REST service where you need to attribute your method to return the result in a specific format (WebMessageFormat), Web APIs allow the client to specify the format they accept, and Web API will format it accordingly. This is achieved by the client specifying the format in the Accept header in the HTTP request. For an example, if you want the data returned as XML, you would set the Accept header in Fiddler like this Accept : application/xml.

Another cool thing about Web APis, is that it allows OData like syntax to query the API it self for an example, if I want to get only the top 2 URL would be like this


However, this to work, you need change your return type IQueryable like this...

public IQueryable<Project> ActiveProjects()


return GetProjectsFromDB(true).AsQueryable();


The URL format for your return the top 2 projects ordering it by ProjectType would be like this..


Web APIs can be self hosted in a console application and also be written in web forms

Thats all i have time for today...

1 comment:

  1. Thank you for this post nairooz, i've been following your posts for years and they are very helpful.

    One question i've have is, what is the best way to pass a complex object as a parameter for a Get method?

    I know for a POST object i can have a JSON or XML serialized object in the request body. Is there a similar way i can do this for Get?

    The only 2 options i'm stuck with right now are:
    1. Use about 10 primitive type parameters in the method signature and build my complex object using these params.

    2. Go out of the 'REST' norm and use POST method for all methods, including the GetXXXX()s.