dotarj / PartialResponse

PartialResponse provides JSON partial response (partial resource) support for ASP.NET Web API.
Other
57 stars 26 forks source link

ASP.NET Web API Partial Response

apache nuget appveyor sonarqube codecov

PartialResponse provides JSON partial response (partial resource) support for ASP.NET Web API. This package is also available for ASP.NET Core MVC.

Getting started

First, add a dependency to WebApi.PartialResponse using the NuGet package manager (console):

Install-Package WebApi.PartialResponse

Then, remove the JsonMediaTypeFormatter from the output formatters and add the PartialJsonMediaTypeFormatter. The fields parameter value, which is used to filter the API response, is case-sensitive by default, but this can be changed using the PartialJsonMediaTypeFormatter.IgnoreCase property:

configuration.Formatters.Clear();
configuration.Formatters.Add(new PartialJsonMediaTypeFormatter() { IgnoreCase = true });

For OWIN self-host or HTTP self-host applications, add the PartialJsonActionFilter to the filters:

configuration.Filters.Add(new PartialJsonActionFilter());

That's it!

Understanding the fields parameter

The fields parameter filters the API response so that the response only includes a specific set of fields. The fields parameter lets you remove nested properties from an API response and thereby reduce your bandwidth usage.

The following rules explain the supported syntax for the fields parameter value, which is loosely based on XPath syntax:

In practice, these rules often allow several different fields parameter values to retrieve the same API response. For example, if you want to retrieve the playlist item ID, title, and position for every item in a playlist, you could use any of the following values:

Note: As with all query parameter values, the fields parameter value must be URL encoded. For better readability, the examples in this document omit the encoding.

Note: Due to the relatively slow performance of LINQ to JSON (Json.NET), the usage of PartialJsonOutputFormatter has a performance impact compared to the regular Json.NET serializer. Because of the reduced traffic, the overhead in time could be neglected.