ASP.NET Web API is a framework for building and consuming HTTP services that can reach a broad range of clients including browsers, phones and tablets. This application consists of a contact manager web API that is used by an ASP.NET MVC application and a Windows Phone application to display and manage a list of contacts.


This sample uses the NuGet package restore feature to install the required set of NuGet packages when the sample is first built. Make sure you have network access to the public NuGet feed on before building this sample the first time.


When you run the application a list of contacts is displayed in the browser along with a form for adding new contacts. You can also remove contacts and view an image of each contact.

The web application includes a link to documentation for the contact manager web API. Click on the API link to view a list of the available HTTP endpoints and the allowed HTTP methods. You can also view a description of the supported parameters and sample request and response message payloads.

Running the application also brings up a Windows Phone application in the Windows Phone emulator. NOTE: The Windows Phone app is currently not supported when using Visual Studio 2012 or Windows 8. The Windows Phone application displays the list of contacts and you can click on a contact to see an image for that contact. To refresh the list of contacts as new contacts are added simply click the back key and reload the application

When running on Windows 8 with Visual Studio 2012 you can also run a Windows 8 app to access the Contact Manager data.

The Windows 8 app uses the new HttpClient in .NET 4.5 along with the ASP.NET Web API Client libraries to retrieve and deserialize the contact data.


HttpClient client = new HttpClient(); 
client.BaseAddress = new Uri("http://localhost:8081/"); 
HttpResponseMessage response = await client.GetAsync("api/contacts"); 
Contact[] contacts = await response.Content.ReadAsAsync<Contact[]>();


The contact manage web API is implemented by the ContactsController. The ContactsController handles GET request for the list of contacts and also POST requests for adding new contacts. It also supports PUT and DELETE requests for updating contacts and removing contacts.

The ContactsController is implemented using an IContactRepository to store and retrieve the contacts. The IContactRepository is injected into the controller's constructor using the Ninject IoC container.

Self links for each returned Contact instance are provided by the [ContactSelfLinkFilter] filter, which runs for every request to the ContactsController. The self links are generated using the UrlHelper.

The ASP.NET MVC application uses jQuery to retrieve the list of contacts from the web API as JSON and then binds the contact data to the UI using knockout.js.

Because ASP.NET Web API supports HTTP content negotiation the contact data can also be retrieved as XML.

The client can specify the desired media type by either using the HTTP Accept header or using a custom URI path extension. The URI path extension support is provided by adding UriPathExtensionMappings to each of the configured set of formatters and by adding routes to allow for the extensions.

In addition to the built-in support for JSON and XML in ASP.NET Web API the sample adds a custom MediaTypeFormatter so that the contact data can be retrieved in the vCard electronic business card format.

You can also use the OData query syntax to query over the list of contacts. For example, you can use the $top operator to request just the first two contacts.

Support for the OData query syntax is enabled by returning an instance of IQueryable from an action and attributing the action with the [Queryable] filter.

More Information

ASP.NET Web API home page