Last week at MIX11, Preview 4 of WCF Web API was released. If you missed it, you can watch the video here. One way to get Preview 4 and start playing with it is to download it here. However, an even easier way to to just grab the bits from NuGet:
When you download the latest Web API bits, there are a couple of sample applications that show off the latest features of the Web API (these are in the CodePlex download, not the NuGet packages). The first one is a Contact Manager "Simple" project which is intended to show just how simple it is to consume the Web API framework. There is also another sample which shows the advanced features such as IoC support, custom media type formatters, channels, and more.
I like to create a lot of "Hello World" applications when I'm learning a new technology for the first time or even when I just want to do some quick tests for a technology I already know pretty well. The existing Web API NuGet packages certainly help us add the references quickly. However, there is an even quicker way to get up and running with the new Web API – sample NuGet packages. Since NuGet has such rich functionality beyond adding references such as adding start code and configuration, there are many packages that exist to get you up and running fast. David Ebbo highlighted this last month in his post: Take NuGet to the next level with sample packages.
Taking all this into account, I created a "WebApi.CrudHttpSample" NuGet package. This allows you to fire up a brand new instance of Visual Studio, File – New Project, add the package and you are up and running. The Web API assemblies are added via NuGet dependencies and starter code is added as well. You can just select an "ASP.NET Empty Web Application" without having to worry about selecting some special WCF project template. This will have nothing in it but an empty web.config file. Now you can add the package:
PM> Install-Package WebApi.CrudHttpSample
This first thing you'll see is a "dummy" model class that looks like this:
// TODO: Use Visual Studio refactoring to rename "MyModelType" to your desired type.
// Then you can move the model to its own file.
public class MyModelType
{
public int Id { get; set; }
}
Use Visual Studio refactoring to rename this class. It's important to use the VS.NET refactoring because the type is referenced elsewhere in the starter code so this will rename it appropriately everywhere. I'll rename it to "Contact" and add a couple of properties to it:
public class Contact
{
public int Id { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
}
The next thing you'll see is a resource class called "MyModelResource". Again, you should use VS.NET refactoring to rename it to something that is sensible for your application. I'll rename it to "ContactResource" (this is a similar approach to the starter code in the REST Start Kit from a couple years ago – of course they didn't have NuGet at their disposal!). The code looks like this:
[ServiceContract]
public class ContactResource
{
// TODO: replace with your own "real" Repository implementation
private static readonly Dictionary<int, Contact> repository = new Dictionary<int, Contact>();
[WebGet(UriTemplate = "{id}")]
public HttpResponseMessage<Contact> Get(int id)
{
Contact item;
if (!repository.TryGetValue(id, out item))
{
var notFoundResponse = new HttpResponseMessage();
notFoundResponse.StatusCode = HttpStatusCode.NotFound;
notFoundResponse.Content = new StringContent("Item not found");
throw new HttpResponseException(notFoundResponse);
}
var response = new HttpResponseMessage<Contact>(item);
// set it to expire in 5 minutes
response.Content.Headers.Expires = new DateTimeOffset(DateTime.Now.AddSeconds(30));
return response;
}
[WebInvoke(UriTemplate = "", Method = "POST")]
public HttpResponseMessage<Contact> Post(Contact item)
{
item.Id = (repository.Keys.Count == 0 ? 1 : repository.Keys.Max() + 1);
repository.Add(item.Id, item);
var response = new HttpResponseMessage<Contact>(item);
response.StatusCode = HttpStatusCode.Created;
response.Headers.Location = new Uri("Contacts/" + item.Id, UriKind.Relative);
return response;
}
[WebInvoke(UriTemplate = "{id}", Method = "PUT")]
public Contact Put(int id, Contact item)
{
repository[id] = item;
return item;
}
[WebInvoke(UriTemplate = "{id}", Method = "DELETE")]
public Contact Delete(int id)
{
var deleted = repository[id];
repository.Remove(id);
return deleted;
}
}
There are several things to note about this code. First, I'm just using a static Dictionary for temporary storage. This can be replaced with your "real" repository of choice. The Get() method returns an HttpResponseMessage which is the strongly typed HTTP message available in the Web API. You can see that if the id is not found, we're able to throw an HttpResponseException which is a much more intuitive way of dealing with exceptions than what we have today. I'm also able to set expiration headers – all without referring to the static WebOperationContext. The other methods are similarly easy to work with. It's important to point out that this is not a RESTful service – this is merely a CRUD service over HTTP. Although I do set the location header in the Post() method, I'm not leveraging hypermedia and therefore, not RESTful.
At this point, all I have is a single C# file – how do I get this hooked into the WCF pipeline? The next thing I take advantage of is the WebActivator NuGet package. I follow the established pattern for the "App_Start" folder and put my initialization code in here. This code will automatically be invoked when the web site starts up (no need for Global.asax). Then just change the first URI segment from "MyModel" to whatever you want. I'll change it to "Contacts":
At this point, I can now run my app in Fiddler with all VERBs:
- GET /Contacts/1 – gets an existing contact (404 if it doesn't exist)
- POST /Contacts – specify Content-type: application/type and post Contact xml to insert
- PUT /Contacts/1 – updates existing Contact
- DELETE /Contacts/1 – deletes existing Context
To see the NuGet package in action as well as executing all methods in Fiddler, watch this short (6 minute) video below (if there is a problem with the embedded video, direct video link is here):
A logical next step would be to create a NuGet sample package that contains starter code for more advanced features such as IoC, media type formatters, etc. The Web API is getting better and better. It's now easier and simpler than ever to work with HTTP. Now is the time to start getting familiar with it and provide your feedback to the team.
