The trend for writing web services in the .Net community is moving from SOAP to REST. There are many reasons for this, but the most compelling may be the difference in “weight.” When using SOAP you must wrap everything in an envelope before sending, with the REST protocol you basically just send it. There are very few restrictions on what you can send over.

Consuming these new REST services is very simple and very well understood, and it turns out that writing them using MVC is extremely easy as well. Starting with MVC4 you can use the WebAPI to create a REST service very quickly and using a model that you are familiar with.

The Employee Service

For the purposes of this demo I am going to be creating a service to pull employees. In order to do that I need to create an empty EmployeesController,

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
 
namespace ODataTest.Controllers
{
    public class EmployeesController : ApiController
    {
 
    }
}

As well as an Employee Model:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
 
namespace ODataTest.Models
{
    public class Employee
    { 
        public int Id { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public string ManagerName { get; set; }
    }
}

In the EmployeesController class you can see that I am inheriting from ApiController instead of the normal MVC Controller class. And in a nutshell that is pretty much all you need to do in order to create a REST Service. I told you this was easy right?

My First Call – Get All

This class doesn’t have anything in it so if you were to call this you wouldn’t get anything back, so let’s implement the default call and return all employees. I am not going to create a data access, this is just a demo so I am going to create all my employees in my “Get” method and just return them there.

        [HttpGet]
        public Employee[] Get()
        {
            return new[]
                {
                    new Employee{Id = 1, FirstName = "Tony", LastName = "Stark", ManagerName = "Nick Fury"} ,
                    new Employee{Id = 2, FirstName = "Bruce", LastName = "Banner", ManagerName = "Nick Fury"} ,
                    new Employee{Id = 3, FirstName = "Bruce", LastName = "Campbell", ManagerName = "Bruce Campbell"} ,
                    new Employee{Id = 4, FirstName = "Peter", LastName = "Parker", ManagerName = "Aunt May"}  
                };
        }

There isn’t much here. We have a method named Get that is decorated with the HTTPGet attribute. This is telling the parser that you can call a post against this method. If I call this method I will receive a JSON representation of the Employee object back. I didn’t have to “stringify” this, the MVC parser will take care of all of that for you.

If we wanted to consume this method we would call a URI that matches the following pattern http://<yoururl>/api/Employees and from this call we would receive the following JSON back

JSON from service call

Get Single Employee

That is a pretty simple case, so let’s expand on that. If we wanted a specific employee we would need to add the following method

        public Employee Get(int id)
        {
            var employeeList =  new List<Employee>
                {
                    new Employee{Id = 1, FirstName = "Tony", LastName = "Stark", ManagerName = "Nick Fury"} ,
                    new Employee{Id = 2, FirstName = "Bruce", LastName = "Banner", ManagerName = "Nick Fury"} ,
                    new Employee{Id = 3, FirstName = "Bruce", LastName = "Campbell", ManagerName = "Bruce Campbell"} ,
                    new Employee{Id = 4, FirstName = "Peter", LastName = "Parker", ManagerName = "Aunt May"} 
                };
 
            var emp = employeeList.FirstOrDefault(x => x.Id == id);
            return emp ?? new Employee();
         }

The MVC framework will parse your URI, which should look like http://<yoururl>/api/Employees/1, and then find the correct Get method. This is all done by convention so if the last bit of your URI isn’t an integer this will fail. When I call this service I should get a JSON object back that represents Tony Stark. You may have noticed that I didn’t put the HttpGet attribute on this method. I could put in on there and everything would work fine. It turns out that because the method is named Get, the parser realizes that it is a get method and won’t try to post against it.

Summary

This was a very quick scratching the surface of the WebAPI. I will be posting more about the WebAPI in the coming weeks covering more in depth topics such as posting back to the service to insert data and then using the ODataController to do some neat stuff with sorting and filtering.

To quickly recap what we learned today:

  • Creating REST services with MVC4 and the WebAPI is very simple
  • Instead of using Controller use ApiController to create a REST service
  • Just like using base MVC the WebAPI is very convention based, so things are very easy to follow