ASP.NET Web API: Extending content negotiation with new formats

My last post about ASP.NET Web API content negotiation support gave you basic idea about what content negotiation is and how it works out-of-box. In this post I will show you how to extend Web API content negotiation support and make Web API to output contact data in vCard format.

In the end of my previous post we asked data in vCard format from Web API and got answer as JSON. No errors, just answer in the format that Web API was able to provide. In this posting we will add support for vCard data and I will introduce you some more concepts related to Web API. Our focus is on getting data back in vCard format.

Web API controller

One new thing in ASP.NET MVC 4 is new controller type that supports Web API. The new type is called ApiController and it doesn’t use ActionResults. ActionResults are targeted to wider content output. ApiController works with our model types and therefore it is targeted to API type communication. If it still sounds like mystery to you then take Web API controller as MVC based data service.

With Web API controller I use simple model for contacts:

public class ContactModel
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}

And here is my Web API controller for contacts:

public class ContactsController : ApiController
{
    public IEnumerable<ContactModel> Get()
    {
        return SampleDataProvider.Contacts;
    }
 
    public ContactModel Get(int id)
    {
        return SampleDataProvider.Contacts.FirstOrDefault(c => c.Id == id);
    }
 
    public void Post(ContactModel contact)
    {
        SampleDataProvider.Save(contact);
    }
 
    public void Put(ContactModel contact)
    {
        SampleDataProvider.Save(contact);
    }
 
    public void Delete(int id)
    {
        SampleDataProvider.Delete(id);
    }
}

For this posting this controller is enough. Extension point for content formats is not hidden in Web API controllers. What it means? Well, without affecting Web API controllers we can add support for different content formats over time.

Media type classes

To add vCard support to our Web API we have to use classes that can convert our contact model to vCard and that introduce this format to content negotiation mechanism. I don’t start dissecting internals of content negotiation deeper because it deserver separate posting. In this posting we will build up two media type classes that do the work we need.

MediaTypeMapping class

Our first class is media type mapper. This class extends MediaTypeMapping – the base class for all media type mappers. In this class we say that vCard format is supported 100% if client accepts this format.

public class VCardMediaTypeMapping : MediaTypeMapping
{
    public VCardMediaTypeMapping() : base("text/x-vcard")
    { }
 
    protected override double OnTryMatchMediaType(HttpResponseMessage response)
    {
        if (response.RequestMessage.Headers.Accept.Count(m => m.MediaType == "text/x-vcard") > 0)
            return 1.0;
 
        return 0.0;
    }
 
    protected override double OnTryMatchMediaType(HttpRequestMessage request)
    {
        throw new NotImplementedException();
    }
}

Our next class is media type formatter.

MediaTypeFormatter class

MediaTypeFormatter is base class for all media type formatters. Media type formatters take object and convert it to format they support. In our case we need media type formatter that takes our contact model and outputs vCard.

public class vCardMediaTypeFormatter : MediaTypeFormatter
{
    public vCardMediaTypeFormatter()
    {
        SupportedMediaTypes.Clear();
        SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/x-vcard"));
    }
 
    protected override bool CanWriteType(Type type)
    {
        return (type == typeof(IEnumerable<ContactModel>));
    }
 
    protected override Task OnWriteToStreamAsync(Type type, object value, Stream stream, HttpContentHeaders contentHeaders, 
                                                 FormatterContext formatterContext, TransportContext transportContext)
 
    {
        return Task.Factory.StartNew(() =>
        {
            WriteVCard((IEnumerable<ContactModel>)value, stream);
        });
    }
 
    private void WriteVCard(IEnumerable<ContactModel> contactModels, Stream stream)
    {
        var enumerator = contactModels.GetEnumerator();
        while (enumerator.MoveNext())
        {
            var contactModel = enumerator.Current;
            var buffer = new StringBuilder();
            buffer.AppendLine("BEGIN:VCARD");
            buffer.AppendLine("VERSION:2.1");
            buffer.AppendFormat("N:{0};{1}\r\n", contactModel.LastName, contactModel.FirstName);
            buffer.AppendFormat("FN:{0} {1}\r\n", contactModel.FirstName, contactModel.LastName);
            buffer.AppendLine("END:VCARD");
 
            using (var writer = new StreamWriter(stream))
            {
                writer.Write(buffer);
            }
        }
    }
}

One thing to notice is CanWriteType() method. Don’t expect that this method is only called to find out if your model types are supported. This method is also called with generic types where your model types appear. By example, support for IEnumerable<ContactModel> is checked before writing out list of contacts. Why ask about collections? The point is simple – there may be types that cannot be listed by just adding converted objects to output stream.

Introducing new media type to web application

Before testing our application we must introduce to web application that we have support for new media type. This is the point where we put all pieces together and this is why we don’t have to modify our Web API controllers when we add new media formats to our application. Add the following code block to Application_Start method in Global.asax file.

var vcard = new vCardMediaTypeFormatter();
vcard.MediaTypeMappings.Add(new VCardMediaTypeMapping());
 
GlobalConfiguration.Configuration.Formatters.Add(vcard);

What we are doing here is simple. We create new instance of our vCard formatter and add mapping to it that sais that this formatter is able to output vCard. After that we add our formatter to global formatters collection so content negotiation system is able to use it.

Testing our application

Now it’s time to test our application. I’m using same application as in my previous example where we got the following result when asking vCard from Web API:

Last time we got data back in JSON format.

We asked vCard that is not supported OOB.

Now let’s try again and let’s see what is the type of returned content and how it looks:

Content type of response is this time vCard.

Response body is now formatted as vCard.

Okay, here it is – list of contacts as vCard items.

Conclusion

Extending Web API content negotiation with support for new media types gives us the way to support clients better and provide them with richer output formats support. Web API controllers are good for building Web API-s and they are very natural to use. Support for content formats is introduced on application global settings level and we don’t have to modify our Web API controllers when new media formatter is added to system. When developing our web based API we put focus on internals of this API and functionalities it provides. Output formatters are implemented separately and used by Web API through content negotiation mechanism.