In previous articles, we have seen how content negotiation works. We also have seen how additional formatters can be configured to support different types of formatting.

In this article, we are going to have look at how the URL can be used to decide format of response instead of accept header.

Why ?

Generally, it may never be a requirement for APIs to format the response based on URL. In some cases, where the data is getting published to external systems, it might a requirement to format data based on preferences provided by those external systems.

But even in that case, if the external systems can pass http headers, I personally think the default content negotiation approach using http header is better probably.

For some reasons, if the external systems do not want to send or rely on accept http headers, then the approach that is being discussed here may prove handy.

This might also be helpful, if client wants to download a file and then filename and format can come from URL route which would decide formatting of response too.

How ?

There is a filter available for this purpose – and its name is FormatFilter. To understand better about how it works, I checked its source code at GitHub.

It implements IResourceFilter and IResultFilter.

• IResourceFilter adds OnResourceExecuting method, which is invoked just before an action is invoked.
• On the other hand, IResultFilter provides OnResultExecuting method, which is invoked after action has produced result.

OnResourceExecuting Overview

IResourceFilters are executed for incoming request, just after authorization filters but before executing the targeted action.

FormatFilter checks two places to see if a format was specified in URL.

• It first checks if the format was specified in the route using {format} route parameter. It is found then it is used for further processing
• If route parameter is not found, then it tries to find if there is a query string parameter with name format. If query string parameter is found, it is used for response formatting.

If format parameter is not found at all in incoming request, then FormatFilter says in “mute” state, it does not perform any role in formatting the response.

Also, if format parameter was found but the action does not support the asked format, then this filter returns NotFound response.

OnResultExecuting Overview

IResultFilters are executed after result has been produced by action.

In OnResultExecuting,

• It checks if format filter was specified. If format filter was not specified, all other steps are skipped.
• Next, if the result from API is not of type ObjectResult, then also FormatFilter skips the formatting of response.
• If action has some attributes which only allows response in only one format, then also FormatFilter skips its work.

If none of the above is true, then it adds the format in content types collection of result, which can later be picked up by formatters to format response.

Code

So, enough about internal code from the framework. Let’s see a working example. FormatFilter can be placed as an attribute on a controller or an action. Next, the format filter can be specified via RouteAttribute or HTTP method attributes (HttpGet, HttpPost, etc).

Below is a code example which shows how to specify route parameter on an API action via HttpGet attribute.

Below is the output of this API. If the format parameter (either JSON or XML ) is specified, it would return response in that format. If it is unspecified in the route, then it would use default formatter (JSON).

I hope you find this information useful. Let me know your thoughts.