Consuming Web API OData using $resource service of Angular JS

In one of the previous posts, we saw exposing an OData Endpoint from an ASP.NET Web API service and then we consumed it using .NET and JavaScript clients. In this post, we will continue with consuming the service using Angular JS.

$resource is a wrapper around $http service of Angular JS to interact with RESTful data services. If we use $resource, we don’t need to deal with the low level HTTP calls that we used to do with $http.

Since $resource is targeted for REST based services, it has to be configured with the service URL and a few of other optional settings to get it work. Following snippet shows syntax of a sample configuration:

$resource(url, { key:val, .. }, {
    ‘getValues’: {method: ‘GET’, params: { param: val }, … },
    …
    …
});

$resource is not a part of Angular’s core module. To use $resource in an Angular JS application, the module ngResource has to be injected into the module depending on it. To know more about $resource, visit the official documentation page on website of Angular JS.

$resource can be configured to perform all of its operations on a single URL or even the URL can be over-written in the action configuration, if required. To consume a Web API OData service, we need to use the second approach as the URL differs based on the operation we will be performing.

Following factory returns a $resource object to perform CRUD operations on the OData resource:

var app = angular.module('employeeApp', ['ngResource']);
app.factory('employeeSvc', function ($resource) {
    var odataUrl = "/odata/Employees";
    return $resource("", {},
    {
        'getAll': { method: "GET", url: odataUrl },
        'save': { method: "POST", url: odataUrl },
        'update': { method: 'PUT', params: { key: "@key" }, url: odataUrl + "(:key)" },
        'query': { method: 'GET', params: { key: "@key" }, url: odataUrl + "(:key)" },
        'remove': { method: 'DELETE', params: { key: "@key" }, url: odataUrl + "(:key)" }
     });
});

This factory can be injected inside any component and used there. Each action configured above is exposed as a method on the object returned from the factory with a dollar($) symbol prepended to each of them. Since these methods deal with AJAX, they return a $q promise.

Following controller uses the methods defined above to operate on the data service:

app.controller('EmployeeCtrl', function ($scope, employeeSvc) {

    //Getting all employees and assigning to a scope variable           
    function refreshEmployees() {
        (new employeeSvc()).$getAll()
            .then(function (data) {
                $scope.employees = data.value;
            });
    };

    //Add a new employee to the resource
    function createEmployee(emp) {
        return emp.$save();
    };

    //Modify details of an existing employee
    function editEmployee(emp) {
        return (new employeeSvc({
            "Id": emp.Id, "Name": emp.Name, "Salary": emp.Salary
        })).$update({ key: emp.Id });
    };

    //Delete an employee
    function deleteEmployee(id) {
        return (new employeeSvc()).$remove({ key: id });
    };

    //rest of the controller definition.......
});

Take a look at the refreshEmployee function created above. It calls then() on the returned object from the $getAll() method to grab the response as soon as the GET request is completed. As Web API OData sets actual data to the property value, the scope variable is assigned with this property.

Happy coding!

Consuming Web API OData From .NET And JavaScript Client Applications

In last post, I created a Web API OData service that performs CRUD operations on an in-memory collection. In this post, we will consume the service from a .NET client and a web page.

Consuming Web API OData using a .NET client:

A Web API OData service can be consumed using WCF Data Services client. If you gave already worked with WCF Data Services, you already know about consuming Web API OData Service as well.

Right click on a .NET project and choose the option Add Service Reference. In the dialog, enter the OData service URL and click the Go button.

The dialog parses the metadata received from the server and shows the available entities under container as shown in the screenshot. As we created just one entity in the service, we see the entity Employee alone. Name the namespace as you wish and hit OK. Visual Studio generates some classes for the client application based on the metadata.

The generated code contains the following:

1. A Container class, which is responsible for communicating with the service. It holds DataServiceQuery<TEntity> type properties for each EntitySet on the server
2. A class for every entity type. This class contains all properties mapped on the server, information about key of the entity

A Container is much like a DbContext in Entity Framework. It handles all the operations. Container is responsible for building OData URLs and sending requests to the service for any operation that client asks for. Let’s start by creating a Container. Constructor of the container accepts a URI, which is base address of the Web API OData service.

Container container = new Container(new Uri("http://localhost:1908/odata"));

To fetch details of all employees, we need to invoke the Corresponding DataServiceQuery property.

var employees = container.Employees;

Although the statement looks like an in-memory operation, it generates the corresponding URL internally and calls the server. Similarly, to get details of an employee with a given Id, we can write a LINQ query as shown:

var employee = container.Employees.Where(e => e.Id == 3).FirstOrDefault();

The above query makes a call to the Get method accepting key in the Web API Controller.

To create a new employee, we need to create an object of the Employee class, add it and ask Container to save it. Following snippet demonstrates this:

Employee emp = new Employee() { Id = 0, Name = "Hari", Salary = 10000 };
container.AddToEmployees(emp);
container.SaveChanges();

Performing update is also much similar. The difference is with calling the SaveChanges method.

emp = container.Employees.Where(e => e.Id == 3).FirstOrDefault();
emp.Name = "Stacy";
container.UpdateObject(emp);
container.SaveChanges(SaveChangesOptions.ReplaceOnUpdate);

If SaveChanges is called with SaveChangesOptions.ReplaceOnUpdate, it performs PUT operation on the resource. If SaveChangesOptions.PatchOnUpdate is passed, it performs PATCH operation on the resource.

To delete an entry, we need to pass an object to DeleteObject method and just like earlier cases; we need to call the SaveChanges method on the Container.

container.DeleteObject(container.Employees.Where(e => e.Id == 3).FirstOrDefault());
container.SaveChanges();

Consuming Web API OData using JavaScript client:

To consume the Web API OData service from a web page, the service has to be called using AJAX. The client can send an AJAX request to the URL of the OData service by specifying an HTTP verb to operate on the resource. To make our life easier, let’s use jQuery for AJAX calls.

To get details of all employees, we need to send a GET request to the OData URL. Values of entries in the collection are stored in a property named value in the object received as response. Fetching details of an employee with a given Id also follows similar approach. Following snippet demonstrates this:

$.getJSON(“/odata/Employees”, function(data){
    $.each(data.value, function(){
        //Modify UI accordingly
    });
});

$.getJSON(“/odata/Employees(3)”, function(data){
        //Modify UI accordingly
});

To add a new employee, we need to send the new object to $.post along with the URL.

var employee = {
    "Id": 0,
    "Name": “Ravi”,
    "Salary": 10000
};

$.post(“/odata/Employees”, employee).done(function(data){
    //Modify UI accordingly
});

Unfortunately, jQuery doesn’t have a shorthand method for PUT. But it is quite easy with $.ajax as well. To perform PUT on the resource, the request should be sent to the specific address with an ID and the modified object should be passed with the request.

var employee = {
    "Id": 3,
    "Name": “Ravi”,
    "Salary": 10000
};

$.ajax({
url: "/odata/Employees(" + employee.Id + ")",
       type: "PUT",
       data: employee
});

Building request for DELETE is similar to put, we just don’t need to pass the object.

$.ajax({
url: "/odata/Employees(" + id + ")",
type: "DELETE"
});

Happy coding!

Performing CRUD Operations in Web API OData Service using ODataController

OData is a protocol for operating on data over HTTP. OData follows REST architecture. It provides a uniform interface for interacting with data over web and performing CRUD (Create, Read, Update and Delete) operations. It also provides metadata so that the consuming application gets awareness about the types used in the service.

If you are new to OData and want to learn more, checkout the official website for OData and read David Chappel’s whitepaper on OData.

ASP.NET Web API is a solution for creating HTTP services. ASP.NET team added OData support to Web API in the ASP.NET and Web Tools 2012.2 Update. In this post, we will create a simple Web API OData service that performs CRUD operations on an in-memory object collection.

Setting up the project and data:

Fire Visual Studio 2012 or 2013 and create an ASP.NET MVC 4 project with Web API template or, add the following NuGet packages to an empty ASP.NET project:

• Microsoft.Aspnet.WebApi.OData
• Microsoft.AspNet.WebApi.WebHost

Let’s create our data components now. Add a new class to the project, name it Employee and add following properties to it:

public class Employee
{
    public int Id { get; set; }
    public string Name { get; set; }
    public double Salary { get; set; }
}

Add another class named EmployeesHolder. This class will hold a static collection of Employee class created above. We will perform CRUD operations on the data created in this class. Add the following code to the EmployeesHolder class:

public class EmployeesHolder
{
    public static List<Employee> Employees;

    static EmployeesHolder()
    {
        Employees = new List<Employee>();

        Employees.Add(new Employee() { Id = 1, Name = "Jack", Salary = 10000 });
        Employees.Add(new Employee() { Id = 2, Name = "Anthony", Salary = 7000 });
        Employees.Add(new Employee() { Id = 3, Name = "Tracey", Salary = 20000 });
        Employees.Add(new Employee() { Id = 4, Name = "Sherry", Salary = 6000 });
        Employees.Add(new Employee() { Id = 5, Name = "Hill", Salary = 16000 });
    }
}

Creating OData Route

We need to add some configurations when application starts to enable OData in the application. Before defining the route map, we need to build an EDM model with all entity sets to be exposed. It is done as shown below:

     var modelBuilder = new ODataConventionModelBuilder();
     modelBuilder.EntitySet<Employee>("Employees");
     Microsoft.Data.Edm.IEdmModel model = modelBuilder.GetEdmModel();

The ODataConventionalModelBuilder is used to map all entity sets that have to be exposed through OData endpoint. Alternatively, ODataModelBuilder can also be used for this purpose. But if we do so, we need to define each property and relationship using fluent configuration model. ODataConventionalModelBuilder does all that work for us. We just need to add the entity sets to be exposed.

We need to define the OData route using the EDM model created above. It is shown below:

config.Routes.MapODataRoute("ODataRoute", "odata", model);

Creating API Controller and performing read operations

Let’s define a Web API controller to perform CRUD operations over the collection created above. Add an API controller to the application named EmployeesController. Modify the parent class of this class as ODataController.

public class EmployeesController : ODataController
{
}

ODataController is the low-level class to work with OData in Web API. We need to directly deal with HTTP verbs and build response by hand using this class. We have higher level classes available that deal with the verbs. While using them we have to just worry about the data, rest of the things are taken care by the framework. But it is important to understand what is going on behind the scenes to get much of the work done. So, in this post we will create the API using ODataController.

Delete all the default code inside the controller. Add the following method to the controller:

public IQueryable<Employee> Get()
{
    return EmployeesHolder.Employees.AsQueryable();
}

Build and run this application now. Change the URL on your browser to:


http://localhost:<port-no>/odata/Employees

You should be able to see the list of all employees created above in your browser.



Notice the metadata URL in the first statement. Metadata information for the entire application is exposed through this URL.

Let’s add another method to the service that gets details of an employee based on ID.

public HttpResponseMessage Get([FromODataUri]int key)
{
    Employee employee = EmployeesHolder.Employees.Where(e => e.Id == key).SingleOrDefault();
    if (employee==null)
    {
        return Request.CreateResponse(HttpStatusCode.NotFound);
    }

    return Request.CreateResponse(HttpStatusCode.OK, employee);
}

The attribute FromODataUri indicates that the value has to be taken from the requested URL. Change the URL on the browser as:


http://localhost:1908/odata/Employees(2)

Now you should be able to see details of the second employee on the browser:



Web API OData supports a number of query options that can be used to query data from client application. We will explore those options in a future post.

Performing Create operation

HTTP Post method is for adding an item to the resource. It usually accepts data from the client in the HTTP request body. Following Post method adds a new employee to the list we created earlier:

public HttpResponseMessage Post([FromBody]Employee entity)
{
    string name = entity.Name;
    HttpResponseMessage response;
    double salary = entity.Salary;

    try
    {
        int employeeId = EmployeesHolder.Employees.Max(e => e.Id) + 1;

        entity.Id = employeeId;
        EmployeesHolder.Employees.Add(entity);

        response = Request.CreateResponse(HttpStatusCode.Created, entity);
        response.Headers.Add("Location", Url.ODataLink(new EntitySetPathSegment("Employees")));
        return response;
    }
    catch (Exception)
    {
        response = Request.CreateResponse(HttpStatusCode.InternalServerError);
        return response;
    }
}

As you see, the POST method returns a HttpResponseMessage object with the newly created entity embedded in the body. Location is explicitly added to the message because according to the HTTP specification, the location header has to be added to the response header once a POST request is succeeded. The API checks it and the consuming client will return an error if the location is not added.

To test this method, open Fiddler and switch to composer tab. Select POST method from the dropdown and enter the new employee object in JSON format in the request body as shown:



We can assign any value to Id. It will be ignored as we are calculating the next Id in the logic. Hit the Execute button to invoke the service method. Once you see the success status in fiddler, refresh the browser to see the updated employees list.



Performing Update Operation

Update can be performed using either patch or put verb. The difference between these verbs is patch performs partial update on the resource, whereas put replaces the entire entry with the new object received from the client. One of these or both can be chosen based on the needs of the application.

Following Put method modifies the entry at the provided Id in the Employees collection:

public HttpResponseMessage Put([FromODataUri]int key, [FromBody]Employee employee)
{
    var employeeToDeleteEdit = EmployeesHolder.Employees.Where(e => e.Id == key).FirstOrDefault();
    HttpResponseMessage response;
    string name = employee.Name;
    var salary = employee.Salary;

    int index = EmployeesHolder.Employees.FindIndex(e => e.Id == key);
    if (index >= 0)
    {
        EmployeesHolder.Employees[index].Name = name;
        EmployeesHolder.Employees[index].Salary = salary;
    }
    else
    {
        response = Request.CreateResponse(HttpStatusCode.NotFound);
        return response;
    }

    response = Request.CreateResponse(HttpStatusCode.OK, employee);
    return response;
}

Compose a PUT request on Fiddler as shown below:


Click on the Execute button to invoke the corresponding service method. Once the response is received from the server, refresh the browser to see the updated result.



Performing Delete Operation

Delete is a straight forward operation. It just accepts a key and deletes the object at that entry from the resource.

public void Delete([FromODataUri]int key)
{
    var employeeToDelete = EmployeesHolder.Employees.Where(e => e.Id == key).FirstOrDefault();
    if (employeeToDelete != null)
    {
        EmployeesHolder.Employees.Remove(employeeToDelete);
    }
    else
    {
        throw new HttpResponseException(HttpStatusCode.NotFound);
    }
}

Just like Post and Put, let’s test this method using Fiddler. Set a delete request as shown below:



Delete doesn’t accept any object in the body. Click the execute button and once the response is received, refresh browser to see the updated values.



As mentioned earlier, ODataController is the low-level class that helps us in building OData service. Web API’s OData assembly includes another controller that handles most of the plumbing like defining API methods and dealing with HttpResponseMessage. It is EntitySetController.We just need to override a set of methods to work with data in the data while using EntitySetController. Most of the tutorials on ASP.NET site use EntitySetController to work with OData.

Happy coding!