Introduction to the ASP.NET Web API

I am a huge fan of Ajax. If you want to create a great experience for the users of your website – regardless of whether you are building an ASP.NET MVC or an ASP.NET Web Forms site — then you need to use Ajax. Otherwise, you are just being cruel to your customers.

We use Ajax extensively in several of the ASP.NET applications that my company, Superexpert.com, builds. We expose data from the server as JSON and use jQuery to retrieve and update that data from the browser.

One challenge, when building an ASP.NET website, is deciding on which technology to use to expose JSON data from the server. For example, how do you expose a list of products from the server as JSON so you can retrieve the list of products with jQuery? You have a number of options (too many options) including ASMX Web services, WCF Web Services, ASHX Generic Handlers, WCF Data Services, and MVC controller actions.

Fortunately, the world has just been simplified. With the release of ASP.NET 4 Beta, Microsoft has introduced a new technology for exposing JSON from the server named the ASP.NET Web API. You can use the ASP.NET Web API with both ASP.NET MVC and ASP.NET Web Forms applications.

The goal of this blog post is to provide you with a brief overview of the features of the new ASP.NET Web API. You learn how to use the ASP.NET Web API to retrieve, insert, update, and delete database records with jQuery. We also discuss how you can perform form validation when using the Web API and use OData when using the Web API.

Creating an ASP.NET Web API Controller

The ASP.NET Web API exposes JSON data through a new type of controller called an API controller. You can add an API controller to an existing ASP.NET MVC 4 project through the standard Add Controller dialog box.

Right-click your Controllers folder and select Add, Controller. In the dialog box, name your controller MovieController and select the Empty API controller template:

A brand new API controller looks like this:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net.Http;
using System.Web.Http;

namespace MyWebAPIApp.Controllers
{
    public class MovieController : ApiController
    {
    }
}

An API controller, unlike a standard MVC controller, derives from the base ApiController class instead of the base Controller class.

Using jQuery to Retrieve, Insert, Update, and Delete Data

Let’s create an Ajaxified Movie Database application. We’ll retrieve, insert, update, and delete movies using jQuery with the MovieController which we just created. Our Movie model class looks like this:

namespace MyWebAPIApp.Models
{
    public class Movie
    {
        public int Id { get; set; }
        public string Title { get; set; }
        public string Director { get; set; }
    }
}

Our application will consist of a single HTML page named Movies.html. We’ll place all of our jQuery code in the Movies.html page.

Getting a Single Record with the ASP.NET Web API

To support retrieving a single movie from the server, we need to add a Get method to our API controller:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using MyWebAPIApp.Models;

namespace MyWebAPIApp.Controllers
{
    public class MovieController : ApiController
    {

        public Movie GetMovie(int id)
        {
            // Return movie by id
            if (id == 1)
            {
                return new Movie
                {
                    Id = 1,
                    Title = "Star Wars",
                    Director = "Lucas"
                };
            }

            // Otherwise, movie was not found
            throw new HttpResponseException(HttpStatusCode.NotFound);
        }

    }
}

In the code above, the GetMovie() method accepts the Id of a movie. If the Id has the value 1 then the method returns the movie Star Wars. Otherwise, the method throws an exception and returns 404 Not Found HTTP status code.

After building your project, you can invoke the MovieController.GetMovie() method by entering the following URL in your web browser address bar: http://localhost:[port]/api/movie/1 (You’ll need to enter the correct randomly generated port).

In the URL api/movie/1, the first “api” segment indicates that this is a Web API route. The “movie” segment indicates that the MovieController should be invoked. You do not specify the name of the action. Instead, the HTTP method used to make the request – GET, POST, PUT, DELETE — is used to identify the action to invoke.

The ASP.NET Web API uses different routing conventions than normal ASP.NET MVC controllers. When you make an HTTP GET request then any API controller method with a name that starts with “GET” is invoked. So, we could have called our API controller action GetPopcorn() instead of GetMovie() and it would still be invoked by the URL api/movie/1.

The default route for the Web API is defined in the Global.asax file and it looks like this:

routes.MapHttpRoute(
    name: "DefaultApi",
    routeTemplate: "api/{controller}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

We can invoke our GetMovie() controller action with the jQuery code in the following HTML page:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Get Movie</title>
</head>
<body>

    <div>
        Title: <span id="title"></span>
    </div>
    <div>
        Director: <span id="director"></span>
    </div>


    <script type="text/javascript" src="Scripts/jquery-1.6.2.min.js"></script>
    <script type="text/javascript">

        getMovie(1, function (movie) {
            $("#title").html(movie.Title);
            $("#director").html(movie.Director);
        });


        function getMovie(id, callback) {
            $.ajax({
                url: "/api/Movie",
                data: { id: id },
                type: "GET",
                contentType: "application/json;charset=utf-8",
                statusCode: {
                    200: function (movie) {
                        callback(movie);
                    },
                    404: function () {
                        alert("Not Found!");
                    }
                }
            });
        }

    </script>

</body>
</html>

In the code above, the jQuery $.ajax() method is used to invoke the GetMovie() method. Notice that the Ajax call handles two HTTP response codes. When the GetMove() method successfully returns a movie, the method returns a 200 status code. In that case, the details of the movie are displayed in the HTML page.

Otherwise, if the movie is not found, the GetMovie() method returns a 404 status code. In that case, the page simply displays an alert box indicating that the movie was not found (hopefully, you would implement something more graceful in an actual application).

You can use your browser’s Developer Tools to see what is going on in the background when you open the HTML page (hit F12 in the most recent version of most browsers). For example, you can use the Network tab in Google Chrome to see the Ajax request which invokes the GetMovie() method:

Getting a Set of Records with the ASP.NET Web API

Let’s modify our Movie API controller so that it returns a collection of movies. The following Movie controller has a new ListMovies() method which returns a (hard-coded) collection of movies:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http;
using MyWebAPIApp.Models;

namespace MyWebAPIApp.Controllers
{
    public class MovieController : ApiController
    {

        public IEnumerable<Movie> ListMovies()
        {
            return new List<Movie> {
                new Movie {Id=1, Title="Star Wars", Director="Lucas"},
                new Movie {Id=1, Title="King Kong", Director="Jackson"},
                new Movie {Id=1, Title="Memento", Director="Nolan"}
            };
        }



    }
}

Because we named our action ListMovies(), the default Web API route will never match it. Therefore, we need to add the following custom route to our Global.asax file (at the top of the RegisterRoutes() method):

routes.MapHttpRoute(
    name: "ActionApi",
    routeTemplate: "api/{controller}/{action}/{id}",
    defaults: new { id = RouteParameter.Optional }
);

This route enables us to invoke the ListMovies() method with the URL /api/movie/listmovies.

Now that we have exposed our collection of movies from the server, we can retrieve and display the list of movies using jQuery in our HTML page:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>List Movies</title>
</head>
<body>

    <div id="movies"></div>


    <script type="text/javascript" src="Scripts/jquery-1.6.2.min.js"></script>
    <script type="text/javascript">

        listMovies(function (movies) {
            var strMovies="";
            $.each(movies, function (index, movie) {
                strMovies += "<div>" + movie.Title + "</div>";
            });
            $("#movies").html(strMovies);

        });


        function listMovies(callback) {
            $.ajax({
                url: "/api/Movie/ListMovies",
                data: {},
                type: "GET",
                contentType: "application/json;charset=utf-8",
            }).then(function(movies){
                callback(movies);
            });
        }

    </script>



</body>
</html>

 

 

Inserting a Record with the ASP.NET Web API

Now let’s modify our Movie API controller so it supports creating new records:

public HttpResponseMessage<Movie> PostMovie(Movie movieToCreate)
{
    // Add movieToCreate to the database and update primary key
    movieToCreate.Id = 23;

    // Build a response that contains the location of the new movie
    var response = new HttpResponseMessage<Movie>(movieToCreate, HttpStatusCode.Created);
    var relativePath = "/api/movie/" + movieToCreate.Id;
    response.Headers.Location = new Uri(Request.RequestUri, relativePath);
    return response;
}

The PostMovie() method in the code above accepts a movieToCreate parameter. We don’t actually store the new movie anywhere. In real life, you will want to call a service method to store the new movie in a database.

When you create a new resource, such as a new movie, you should return the location of the new resource. In the code above, the URL where the new movie can be retrieved is assigned to the Location header returned in the PostMovie() response.

Because the name of our method starts with “Post”, we don’t need to create a custom route. The PostMovie() method can be invoked with the URL /Movie/PostMovie – just as long as the method is invoked within the context of a HTTP POST request.

The following HTML page invokes the PostMovie() method.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Create Movie</title>
</head>
<body>

    <script type="text/javascript" src="Scripts/jquery-1.6.2.min.js"></script>
    <script type="text/javascript">


        var movieToCreate = {
            title: "The Hobbit",
            director: "Jackson"
        };
        createMovie(movieToCreate, function (newMovie) {
            alert("New movie created with an Id of " + newMovie.Id);
        });


        function createMovie(movieToCreate, callback) {
            $.ajax({
                url: "/api/Movie",
                data: JSON.stringify( movieToCreate ),
                type: "POST",
                contentType: "application/json;charset=utf-8",
                statusCode: {
                    201: function (newMovie) {
                        callback(newMovie);
                    }
                }
            });
        }

    </script>



</body>
</html>

This page creates a new movie (the Hobbit) by calling the createMovie() method. The page simply displays the Id of the new movie:

The HTTP Post operation is performed with the following call to the jQuery $.ajax() method:

$.ajax({
    url: "/api/Movie",
    data: JSON.stringify( movieToCreate ),
    type: "POST",
    contentType: "application/json;charset=utf-8",
    statusCode: {
        201: function (newMovie) {
            callback(newMovie);
        }
    }
});

Notice that the type of Ajax request is a POST request. This is required to match the PostMovie() method.

Notice, furthermore, that the new movie is converted into JSON using JSON.stringify(). The JSON.stringify() method takes a JavaScript object and converts it into a JSON string.

Finally, notice that success is represented with a 201 status code. The HttpStatusCode.Created value returned from the PostMovie() method returns a 201 status code.

Updating a Record with the ASP.NET Web API

Here’s how we can modify the Movie API controller to support updating an existing record. In this case, we need to create a PUT method to handle an HTTP PUT request:

public void PutMovie(Movie movieToUpdate)
{
    if (movieToUpdate.Id == 1) {
        // Update the movie in the database
        return;
    }

    // If you can't find the movie to update
    throw new HttpResponseException(HttpStatusCode.NotFound);
}

Unlike our PostMovie() method, the PutMovie() method does not return a result. The action either updates the database or, if the movie cannot be found, returns an HTTP Status code of 404.

The following HTML page illustrates how you can invoke the PutMovie() method:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Put Movie</title>
</head>
<body>

    <script type="text/javascript" src="Scripts/jquery-1.6.2.min.js"></script>
    <script type="text/javascript">


        var movieToUpdate = {
            id: 1,
            title: "The Hobbit",
            director: "Jackson"
        };
        updateMovie(movieToUpdate, function () {
            alert("Movie updated!");
        });


        function updateMovie(movieToUpdate, callback) {
            $.ajax({
                url: "/api/Movie",
                data: JSON.stringify(movieToUpdate),
                type: "PUT",
                contentType: "application/json;charset=utf-8",
                statusCode: {
                    200: function () {
                        callback();
                    },
                    404: function () {
                        alert("Movie not found!");
                    }
                }
            });
        }

    </script>

</body>
</html>

Deleting a Record with the ASP.NET Web API

Here’s the code for deleting a movie:

public HttpResponseMessage DeleteMovie(int id)
{
    // Delete the movie from the database

    // Return status code
    return new HttpResponseMessage(HttpStatusCode.NoContent);
}

This method simply deletes the movie (well, not really, but pretend that it does) and returns a No Content status code (204).

The following page illustrates how you can invoke the DeleteMovie() action:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Delete Movie</title>
</head>
<body>



    <script type="text/javascript" src="Scripts/jquery-1.6.2.min.js"></script>
    <script type="text/javascript">


        deleteMovie(1, function () {
            alert("Movie deleted!");
        });


        function deleteMovie(id, callback) {
            $.ajax({
                url: "/api/Movie",
                data: JSON.stringify({id:id}),
                type: "DELETE",
                contentType: "application/json;charset=utf-8",
                statusCode: {
                    204: function () {
                        callback();
                    }
                }
            });
        }

    </script>


</body>
</html>

Performing Validation

How do you perform form validation when using the ASP.NET Web API? Because validation in ASP.NET MVC is driven by the Default Model Binder, and because the Web API uses the Default Model Binder, you get validation for free.

Let’s modify our Movie class so it includes some of the standard validation attributes:

using System.ComponentModel.DataAnnotations;
namespace MyWebAPIApp.Models
{
    public class Movie
    {
        public int Id { get; set; }

        [Required(ErrorMessage="Title is required!")]
        [StringLength(5, ErrorMessage="Title cannot be more than 5 characters!")]
        public string Title { get; set; }

        [Required(ErrorMessage="Director is required!")]
        public string Director { get; set; }
    }
}

In the code above, the Required validation attribute is used to make both the Title and Director properties required. The StringLength attribute is used to require the length of the movie title to be no more than 5 characters.

Now let’s modify our PostMovie() action to validate a movie before adding the movie to the database:

public HttpResponseMessage PostMovie(Movie movieToCreate)
{
    // Validate movie
    if (!ModelState.IsValid)
    {
        var errors = new JsonArray();
        foreach (var prop in ModelState.Values)
        {
            if (prop.Errors.Any())
            {
                errors.Add(prop.Errors.First().ErrorMessage);
            }
        }
        return new HttpResponseMessage<JsonValue>(errors, HttpStatusCode.BadRequest);
    }


    // Add movieToCreate to the database and update primary key
    movieToCreate.Id = 23;

    // Build a response that contains the location of the new movie
    var response = new HttpResponseMessage<Movie>(movieToCreate, HttpStatusCode.Created);
    var relativePath = "/api/movie/" + movieToCreate.Id;
    response.Headers.Location = new Uri(Request.RequestUri, relativePath);
    return response;
}

If ModelState.IsValid has the value false then the errors in model state are copied to a new JSON array. Each property – such as the Title and Director property — can have multiple errors. In the code above, only the first error message is copied over. The JSON array is returned with a Bad Request status code (400 status code).

The following HTML page illustrates how you can invoke our modified PostMovie() action and display any error messages:

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
    <title>Create Movie</title>
</head>
<body>

    <script type="text/javascript" src="Scripts/jquery-1.6.2.min.js"></script>
    <script type="text/javascript">


        var movieToCreate = {
            title: "The Hobbit",
            director: ""
        };

        createMovie(movieToCreate,
            function (newMovie) {
                alert("New movie created with an Id of " + newMovie.Id);
            },
            function (errors) {
                var strErrors = "";
                $.each(errors, function(index, err) {
                    strErrors += "*" + err + "n";
                });
                alert(strErrors);
            }
        );


        function createMovie(movieToCreate, success, fail) {
            $.ajax({
                url: "/api/Movie",
                data: JSON.stringify(movieToCreate),
                type: "POST",
                contentType: "application/json;charset=utf-8",
                statusCode: {
                    201: function (newMovie) {
                        success(newMovie);
                    },
                    400: function (xhr) {
                        var errors = JSON.parse(xhr.responseText);
                        fail(errors);
                    }
                }
            });
        }

    </script>


</body>
</html>

The createMovie() function performs an Ajax request and handles either a 201 or a 400 status code from the response. If a 201 status code is returned then there were no validation errors and the new movie was created.

If, on the other hand, a 400 status code is returned then there was a validation error. The validation errors are retrieved from the XmlHttpRequest responseText property. The error messages are displayed in an alert:

(Please don’t use JavaScript alert dialogs to display validation errors, I just did it this way out of pure laziness)

This validation code in our PostMovie() method is pretty generic. There is nothing specific about this code to the PostMovie() method. In the following video, Jon Galloway demonstrates how to create a global Validation filter which can be used with any API controller action:

http://www.asp.net/web-api/overview/web-api-routing-and-actions/video-custom-validation

His validation filter looks like this:

using System.Json;
using System.Linq;
using System.Net;
using System.Net.Http;
using System.Web.Http.Controllers;
using System.Web.Http.Filters;

namespace MyWebAPIApp.Filters
{
    public class ValidationActionFilter:ActionFilterAttribute
    {
        public override void OnActionExecuting(HttpActionContext actionContext)
        {
            var modelState = actionContext.ModelState;
            if (!modelState.IsValid)
            {
                dynamic errors = new JsonObject();
                foreach (var key in modelState.Keys)
                {
                    var state = modelState[key];
                    if (state.Errors.Any())
                    {
                        errors[key] = state.Errors.First().ErrorMessage;
                    }
                }
                actionContext.Response = new HttpResponseMessage<JsonValue>(errors, HttpStatusCode.BadRequest);
            }
        }
    }
}

And you can register the validation filter in the Application_Start() method in the Global.asax file like this:

GlobalConfiguration.Configuration.Filters.Add(new ValidationActionFilter());

After you register the Validation filter, validation error messages are returned from any API controller action method automatically when validation fails. You don’t need to add any special logic to any of your API controller actions to take advantage of the filter.

Querying using OData

The OData protocol is an open protocol created by Microsoft which enables you to perform queries over the web. The official website for OData is located here:

http://odata.org

For example, here are some of the query options which you can use with OData:

· $orderby – Enables you to retrieve results in a certain order.

· $top – Enables you to retrieve a certain number of results.

· $skip – Enables you to skip over a certain number of results (use with $top for paging).

· $filter – Enables you to filter the results returned.

The ASP.NET Web API supports a subset of the OData protocol. You can use all of the query options listed above when interacting with an API controller. The only requirement is that the API controller action returns its data as IQueryable.

For example, the following Movie controller has an action named GetMovies() which returns an IQueryable of movies:

public IQueryable<Movie> GetMovies()
{
    return new List<Movie> {
        new Movie {Id=1, Title="Star Wars", Director="Lucas"},
        new Movie {Id=2, Title="King Kong", Director="Jackson"},
        new Movie {Id=3, Title="Willow", Director="Lucas"},
        new Movie {Id=4, Title="Shrek", Director="Smith"},
        new Movie {Id=5, Title="Memento", Director="Nolan"}
    }.AsQueryable();
}

If you enter the following URL in your browser:

/api/movie?$top=2&$orderby=Title

Then you will limit the movies returned to the top 2 in order of the movie Title. You will get the following results:

By using the $top option in combination with the $skip option, you can enable client-side paging. For example, you can use $top and $skip to page through thousands of products, 10 products at a time.

The $filter query option is very powerful. You can use this option to filter the results from a query. Here are some examples:

Return every movie directed by Lucas:

/api/movie?$filter=Director eq ‘Lucas’

Return every movie which has a title which starts with ‘S’:

/api/movie?$filter=startswith(Title,’S’)

Return every movie which has an Id greater than 2:

/api/movie?$filter=Id gt 2

The complete documentation for the $filter option is located here:

http://www.odata.org/developers/protocols/uri-conventions#FilterSystemQueryOption

Summary

The goal of this blog entry was to provide you with an overview of the new ASP.NET Web API introduced with the Beta release of ASP.NET 4. In this post, I discussed how you can retrieve, insert, update, and delete data by using jQuery with the Web API.

I also discussed how you can use the standard validation attributes with the Web API. You learned how to return validation error messages to the client and display the error messages using jQuery.

Finally, we briefly discussed how the ASP.NET Web API supports the OData protocol. For example, you learned how to filter records returned from an API controller action by using the $filter query option.

I’m excited about the new Web API. This is a feature which I expect to use with almost every ASP.NET application which I build in the future.