DataFilters.AspNetCore 0.3.0

.NET 5.0 This package targets .NET 5.0. The package is compatible with this framework or higher. .NET Standard 2.1 This package targets .NET Standard 2.1. The package is compatible with this framework or higher.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package DataFilters.AspNetCore --version 0.3.0                

                    
                

            
NuGet\Install-Package DataFilters.AspNetCore -Version 0.3.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="DataFilters.AspNetCore" Version="0.3.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add DataFilters.AspNetCore --version 0.3.0                

                    
                

            
#r "nuget: DataFilters.AspNetCore, 0.3.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install DataFilters.AspNetCore as a Cake Addin
#addin nuget:?package=DataFilters.AspNetCore&version=0.3.0

// Install DataFilters.AspNetCore as a Cake Tool
#tool nuget:?package=DataFilters.AspNetCore&version=0.3.0

GitHub Workflow Status (main) GitHub Workflow Status (develop) codecov GitHub raw issues Nuget

DataFilters.AspNetCore

Table of contents

  • <a href='#why'>Why</a>
    • <a href='#build-ifilters'>Make it easier to build IFilter instances</a>
    • <a href='#reduce-bandwith-usage'>Reduce bandwith usage</a>
      • <a href='#custom-http-headers'>Custom HTTP headers</a>
      • <a href='#prefer-http-header-support'>Prefer HTTP header support</a>
  • <a href='#how-to-install'>How to install</a>

A small library that ease usage of DataFilters with ASP.NET Core APIs.

<a href="#" id="why">Why</a>

<a href="#" id="build-ifilters">Make it easier to build IFilter instances</a>

DataFilters allows to build complex queries in a "restfull" way so However, it comes with some drawbacks.

In order to build a filter, you have to :

  1. parse the incoming string
  2. map it manually to an underlying model type.
  3. converts it into an IFilter instance using the ToFilter<T> extension method.

This can be a tedious task and this library can help to ease that process.

<a href="#" id="reduce-bandwith-usage">Reduce the bandwith usage</a>

The library can help reduce bandwith usage. This can be done in two differnet ways :

  • using x-datafilters-fields-include / x-datafilters-fields-exclude custom HTTP headers
  • using [Prefer] HTTP header, .
<a href="#" id="custom-http-headers"> Custom HTTP headers</a>
x-datafilters-fields-include

x-datafilters-fields-include custom HTTP header allows to specified which properties that will be kept in the body response.

x-datafilters-fields-exclude

x-datafilters-fields-exclude custom HTTP header allows to specify which properties that will be dropped from the body response.

These custom headers can be handy for mobile clients that query a REST API by reducing the volume of data transfered from backend. This can also allow to design one API that can serve multiple clients : each client could "select" the properties it want to display.

<a href="#" id="prefer-http-header-support">Prefer HTTP header support</a>

This library offers a limited support of the Prefer HTTP header. Specifically, a client can request a "minimal" representation of the resource by setting the Prefer: return=minimal HTTP header.

Given the following request

GET /api/users HTTP/1.1

Prefer: return=minimal

and the following C# class where the MinimalAttribute is applied to both Name and Id properties :

public class Person
{
    [Minimal]
    public Guid Id { get; set; }
    [Minimal]
    public string Name { get; set; }
    public string Email { get; set; }
}

the server can respond with a "minimal" representation of the resource.

HTTP/1.1 200 OK

<headers omitted for brevity>

[
   {
       "id": "83c39be2-5123-47bf-a1d1-9df15d146e6a",
       "name": "John Doe"
   },
   {
       "id": 2,
       "name": "Jane Doe"
   }
]

Only properties marked with the MinimalAttribute are returned.

💡 <strong> Usage of the MinimalAttribute automatically triggers support of the Prefer HTTP header.</strong>

Improve performances

The library comes with a IDataFilterService that can be used to build caches IFilter instances created by the service.

<a href='#' id='how-to-install'>How to install</a>

  1. run dotnet install DataFilters.AspNetCore to add the package to your solution
  2. add the following line to your Startup.cs file
public void ConfigureServices(IServiceCollection services)
{
   services.AddDataFilterService(options => 
   {
         // configure DataFiltersOptions
   });
}

This will add IDataFilterService as a singleton to the dependency injection container.

  1. You can also opt in to use the custom HTTP headers by adding and instance of SelectPropertiesActionFilterAttribute
services.Filters.Add(new SelectPropertyFilterAttribute());

This will then enable usage of x-datafilters-fields-include and x-datafilters-fields-exclude HTTP headers

Product Compatible and additional computed target framework versions.
.NET net5.0 is compatible.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.1 is compatible. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.4.0 2,913 8/17/2022
0.3.0 443 8/14/2022
0.2.0 571 3/29/2022
0.1.0 388 5/16/2021
0.1.0-beta0001 294 5/15/2021

• Added [MinimalAttribute](/src/DataFilters.AspNetCore/Attributes/MinimalAttribute.cs) to support Prefer: return=minimal HTTP header ([#47](https://github.com/candoumbe/DataFilters.AspNetCore/issues/47))

Full changelog at https://github.com/candoumbe/DataFilters.AspNetCore/blob/main/CHANGELOG.md