Table of Contents

Filtering

MapCrud enables powerful and intuitive filtering of results directly through query parameters. API consumers can filter data by matching any public property of the entity.

How to Use

When an entity is mapped with app.MapCrud<TEntity>(), the endpoint that retrieves multiple entities (e.g., GET /your-entity-route) automatically supports filtering.

To filter, simply include query parameters where the parameter name matches a public property name on your entity, and the value is what you want to filter by.

  • MapCrud primarily supports exact matches for filtering out-of-the-box.
  • For string properties, this means the property value must exactly match the provided query parameter value.
  • For numeric or boolean properties, it's also an exact match.
  • The matching is generally case-insensitive for property names but case-sensitive for property values by default, though this can vary based on the database configuration if using Entity Framework Core.

Example Model

Let's use a User model for these examples:

public class User
{
    public int Id { get; set; }
    public string Username { get; set; }
    public string Email { get; set; }
    public int Age { get; set; }
    public bool IsActive { get; set; }
}

Mapped as:

app.MapCrud<User>("/users");

Requesting Filtered Data

Clients can filter data by adding query parameters corresponding to the User model's properties.

Example 1: Get all users with the Username "johndoe"

curl "http://localhost:5000/users?Username=johndoe"

URL: http://localhost:5000/users?Username=johndoe

Example 2: Get all users with Age 30

curl "http://localhost:5000/users?Age=30"

URL: http://localhost:5000/users?Age=30

Example 3: Get all users who are active (IsActive is true)

curl "http://localhost:5000/users?IsActive=true"

URL: http://localhost:5000/users?IsActive=true

Example 4: Get all users with Email "jane@example.com" AND Age 25

curl "http://localhost:5000/users?Email=jane@example.com&Age=25"

URL: http://localhost:5000/users?Email=jane@example.com&Age=25

Advanced Filtering Considerations

  • Partial Matches/Contains: MapCrud's default filtering performs exact matches. If you need "contains," "starts with," "greater than," "less than," etc., you would typically need to:
    1. Extend the IRepository implementation with custom filtering logic.
  • Null Values: Querying for null values (e.g., ?MiddleName=null) might have varying behavior based on the repository implementation.
  • Data Types: Ensure the query parameter values can be correctly converted to the property's data type. For example, sending "abc" for an Age (integer) property will likely result in an error or no matches.

OpenAPI (Swagger) Behavior

MapCrud dynamically adds filterable properties as query parameters to the OpenAPI specification for the relevant GET endpoints.

For the GET /users endpoint, using the User model above, Swagger UI would display:

  • Username (string, query, optional): Filter by Username.
  • Email (string, query, optional): Filter by Email.
  • Age (integer, query, optional): Filter by Age.
  • IsActive (boolean, query, optional): Filter by IsActive status.

This makes the available filters discoverable and easy to test directly from the API documentation. The standard pagination (page, pageSize) and sorting (sortBy) parameters will also be listed alongside these filter parameters.

Combining with Pagination and Sorting

Filtering can be combined with Pagination and Sorting in the same request.

Example: Get active users, aged 28, sorted by username, first page, 10 results per page.

curl "http://localhost:5000/users?IsActive=true&Age=28&sortBy=Username&page=1&pageSize=10"

URL: http://localhost:5000/users?IsActive=true&Age=28&sortBy=Username&page=1&pageSize=10

Edit this page