WebApi: CustomMediaTypeMappings in Web API MVC 4

In this article I'll explain Custom MediaTypeMappings in the WebApi.

From the ASP.NET Web API perspective, serialization is the process of translating a .NET Common Language Runtime (CLR) type into a format that can be transmitted over HTTP. The default format is either JSON or XML

A media type formatter, which is an object of type MediaTypeFormatter, performs the serialization in the ASP.NET Web API pipeline. Consider a simple action method handling GET in an ApiController:

Employee Class Code

By default the ASP.NET Web API framework supports two media or content types: JSON and XML.If you send a request with Accept: application/json then the response message will be JSON and Content-Type will be application/json. Similarly, if you send a request with Accept: application/xml, the response message will be XML. You can also specify a quality value indicating the relative preference. The range is 0–1, with 0 being unacceptable and 1 being the most preferred. The default value is 1. For example, if you send the request header Accept: application/json; q=0.8, application/xml;q=0.9 then the response message will be XML, because application/xml has a quality value of 0.9, that is higher than the quality value of 0.8 specified for application/json.

Kindly can also visit this series of articles to learn about the WebApi:

MediaType Mapping

There is one more way by which the Conneg algorithm decides about the Response's media type and formatter. It is called MediaTypeMapping. Every MediaTypeFormatter has a collection of these mappings in it.

MediaTypeMapping provides a way for the user to add some custom logic and decide whether they would want the formatter to take part in writing the Response. This is different from the default way of just matching media type values (like “application/xml”, “application/xml”) present on the Accept and Request Content-Type headers and making decisions.


Let's create a sample application and do this step-by-step.

Step 1: Let's first create a sample web application using an ASP.NET MVC 4 Web Application and name it as you choose; I used WebApiDemo as shown in the image below:

Create MVC 4 App

Step 2: Click OK and choose the Web API option from the templates shown in the wizard window.

Web API Project Template

Step 3: You'll find the application structure as shown below at first sight.

Application Structure

Step 4: Right-click the Controllers folder in the Solution Explorer of Visual Studio. Select "Add" ➤"Controller" and provide a name of EmployeesController for the controller. Leave the option Empty API Controller selected in the Template dropdown and click "Add", as shown in the figure below. Notice that the generated controller class inherits from ApiController, a class that is part of the ASP.NET Web API framework. Kinldy add the following code into the EmployeesController class.

public static IList<Employee> listEmp = new List<Employee>()


    new Employee()


        ID =001, FirstName="Sachin", LastName="Kalia",Department="Engineering"


     new Employee()


        ID =002, FirstName="Dhnanjay" ,LastName="Kumar",Department="Engineering"


    new Employee()


        ID =003, FirstName="Ravish", LastName="Sindhwani", Department="Finance"


     new Employee()


        ID =004, FirstName="Amit" ,LastName="Chaudhary",Department="Architect"


     new Employee()


        ID =004, FirstName="Anshu" ,LastName="Aggarwal",Department="HR"




Adding Controller

Step 5: Right-click the Models folder in the Solution Explorer of Visual Studio. Select "Add" -> "Class"
to add a new class with a name of Employee.

Adding Class

After creating the Employee class, kindly add the following code into this class.

Employee Class

Now I've added a class CustomMediaTypeMapping that checks if the Request has an “AcceptLanguage” Header called “en-FR”. If it finds the header, then it would inform the Conneg algorithm that it's a full match and that the media type formatter having this MediaTypeMapping is ready to write the response.

Class Code

Note: If you notice, we've overridden TryMatchMediaType that takes HttpRequestMessage and returns “The quality of the match. It must be between 0.0 and 1.0. A value of 0.0 signifies no match. A value of 1.0 signifies a complete match”.


Now the question arises, which MediaTypeFormatter will respond to such a MediaTypeMapping. The answer is, add the line given below to the WebApiConfig.cs file placed in the App_Start folder.


It means that whenever a request has Accept-Language: en-FR, JsonFormatter will respond to such a request to the client.

Press F5 and run your application; it will show the following image:

MVC 4 Home Page

Great; the WebApi is up and running.

Now I paste the following URL http://localhost:57888/api/employees/1 into Fiddler and press execute. It responded in application/xml because it has a quality factor of 0.9 that is more than others in the Accept header field as depicted in the following image.


Now I make a slight change to the URL request. Paste the following URL into Fiddler with the same Accept header though this time I have changed the Accept-Language to “en-FR”. Kindly have a look at the image given below:


This time we expect the result in application/json format. Press the execute button.



It responds with a CustomMediaTypeMapping that we've registered in JsonFormatter in WebApiConfig.



In this article we looked into CustomMediaTypeMapping of the WebApi and a way to register with MediaTypeFormatter. I hope you enjoyed this demonstration.

I hope it will help you somewhere down the line. Keep coding and Smile.

Sachin Kalia