Gunnar Peipman's ASP.NET blog

ASP.NET, C#, SharePoint, SQL Server and general software development topics.

Sponsors

News

 
 
 
DZone MVB

Links

Social

April 2012 - Posts

ASP.NET Web API: Query string based content formatting

My previous post about Web API content negotiation showed how to add support for new content formats. As our API may have consumers who prefer query for data using GET requests we have to offer something for these dudes too. In this post I will show you how to make life easier for our Web API consumers by using query string mappings.

I will use media type mapping and formatter from my previous posting Extending content negotiation with new formats. We have to modify code a little bit because we need also single vCard download.

Media type formatter

Here is my media type formatter for vCard. It supports vCard format for single and multiple results. Multiple results are given to write method as IEnumerable<ContactModel>.


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>) ||

               type == typeof(ContactModel);

    }

 

    protected override Task OnWriteToStreamAsync(Type type, object value, Stream stream, HttpContentHeaders contentHeaders, FormatterContext formatterContext, TransportContext transportContext)

    {

        return Task.Factory.StartNew(() =>

        {

            if (type == typeof(ContactModel))

                WriteVCard((ContactModel)value, stream);

            else

                WriteVCard((IEnumerable<ContactModel>)value, stream);

        });

    }

 

    private void WriteVCard(ContactModel model, Stream stream)

    {

        var buffer = new StringBuilder();

        buffer.AppendLine("BEGIN:VCARD");

        buffer.AppendLine("VERSION:2.1");

        buffer.AppendFormat("N:{0};{1}\r\n", model.LastName, model.FirstName);

        buffer.AppendFormat("FN:{0} {1}\r\n", model.FirstName, model.LastName);

        buffer.AppendLine("END:VCARD");

 

        using (var writer = new StreamWriter(stream))

        {

            writer.Write(buffer);

        }

    }

 

    private void WriteVCard(IEnumerable<ContactModel> contactModels, Stream stream)

    {

        var enumerator = contactModels.GetEnumerator();

        while (enumerator.MoveNext())

        {

            WriteVCard(enumerator.Current, stream);

        }

    }

}


Query string mapping

Now let’s say to our web application that contacts API support vCard also with GET requests. QueryStringMapping class will help us out. We just add correctly initialized query string mapping to vCard media type formatter.


var vcard = new vCardMediaTypeFormatter();

vcard.MediaTypeMappings.Add(new VCardMediaTypeMapping());

vcard.MediaTypeMappings.Add(new QueryStringMapping("format", "vcard", "text/x-vcard"));

 

GlobalConfiguration.Configuration.Formatters.Add(vcard);


One thing to notice – we made no changes to our API to add support for vCards and query string mappings. Our API provides only functionality and it doesn’t make any decision about output formatting.

Testing query string

Now it’s time to test our query string mapping. We don’t mess with AJAX-requests anymore because we can conveniently use out browser. If I want to download contact that has ID value 11 over Web API I have to use the following query string:

http://my-app/api/contacts/11/?format=vcard

I will also open IE developer tools to monitor traffic. This is what was returned to browser:

Single vCard response

But now something weird happens – browser asks if we want to open vCard we just requested. Let’s say yes. Here is what you should see on the screen:

vCard opened on desktop

This is good example about how we can use our API in “mixed” mode. We can exchange data between systems but we can also let user to handle some results directly.

Conclusion

Our API can be consumed by different AJAX-clients but now we also made our API easier to use for guys who can easily make GET-requests. By example, PHP guys can use fopen() to make GET-request to our API controller. As we saw we can also use those GET-requests to let end users handle formatted downloads.

Posted: Apr 23 2012, 09:24 AM by DigiMortal | with 3 comment(s)
Filed under:
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:

Default response to request for unknown format
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:

Response content type is now vCard
Content type of response is this time vCard.

Response is valid vCard now
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.

Posted: Apr 20 2012, 11:11 AM by DigiMortal | with 8 comment(s)
Filed under:
ASP.NET Web API: How content negotiation works?

One cool new feature that ASP.NET Web API introduces is support for content negotiation. Content negotiation is mechanism that allows web server to serve content in different format using same URL. In this posting I will show you how to use ASP.NET Web API to serve content in JSON and XML formats.

How content negotiation works

Content negotiation takes place when browser or some other HTTP-client tells server what content formats it accepts. HTTP-client uses Accept header to list all formats it can read. Accept: */* means that client is okay with every content format that server is able to provide. By example, one HTTP-client may accept content in JSON and the other in XML.

Two possible things can happen as a result of negotiation. Client and server agree with format or they don’t. In latter case server gives content out in its default format and it is up to client to get something done with this answer (log an error, by example).

Web API and content negotiation

In this posting we will focus on basic content negotiation support offered by ASP.NET Web API. I will show you how to extend Web API content negotiation in later postings. First we take a look how things work out-of-box and then we try to make things work like we want. We will play with built-in features in this posting.

Let’s suppose we have simple database with contact data and we want to use this database from some other system or from some browser-based AJAX-application. On contact data form I have button that helps me making AJAX-requests to Web API.

ASP.NET Web API test application

Here is the code behind Get Data button:


$.ajax({     type: 'GET',
    url:
"api/contacts/" });

This code just asks data from Web API and returns some data. When we click the button we get the following response:

Content negotiation: Response type is application/json

Content negotiation: JSON response

Now let’s change the code behind button and let’s specify that we want data back in XML:


$.ajax({
    beforeSend: function
(req) {
         req.setRequestHeader(
"Accept", "text/xml"
);
     },
     type:
'GET'
,
     url:
"api/contacts/"
});

Browser sends now Accept header with value text/xml. The answer from server is here:

Content negotiation: Response is XML

Content negotiation: Response data as XML

Okay, we got data in JSON and XML and both of these formats are widely accepted by tools on different platforms.

What if client and server doesn’t agree?

Now let’s try out what happens when we ask something that Web API doesn’t support out-of-box. Perfect fit for contacts should be vCard:


$.ajax({
    beforeSend: function
(req) {
        req.setRequestHeader(
"Accept", "text/x-vcard"
);
    },
    type:
'GET'
,
    url:
"api/contacts/"
});

The result is here:

Content negotiation: Response type is application/json

Content negotiation: JSON response

What we got is same JSON we saw in our first experiment. Web API was not able to convert response to vCard and instead of failing or throwing nasty exceptions it gave us our default answer – JSON.

Conclusion

Built-in content negotiation helps us server same content in different formats to different clients. Clients have to say what format they expect and as long as Web API is able to convert results to this format the client gets content in format it asked it. Providing more than one content format with our API is only good – it makes other developers way easier to use our API with tools they have and this way our API finds more serious users easily.

Posted: Apr 19 2012, 12:12 PM by DigiMortal | with 11 comment(s)
Filed under:
More Posts