Skip to content

filtering-and-pagination.md

Latest commit

 

History

History
145 lines (104 loc) · 4.57 KB

filtering-and-pagination.md

File metadata and controls

145 lines (104 loc) · 4.57 KB

Filtering and Pagination

Snaapi supports Django-style filtering, sorting, and pagination on all list endpoints (GET /v1/:resourceName). Combine query parameters to retrieve exactly the data you need.

Filter Syntax

Filters use the field__operator=value pattern appended as query parameters:

GET /v1/posts?title__like=tutorial&status__eq=published

When no operator is specified, eq (equals) is assumed:

GET /v1/posts?status=published

Multiple filters on different fields are combined with AND logic.

Filter Operators

Snaapi supports 12 filter operators for querying resource records.

Comparison Operators

Operator Description Example
eq Equal to status__eq=active
neq Not equal to status__neq=archived
gt Greater than price__gt=100
gte Greater than or equal to price__gte=100
lt Less than quantity__lt=10
lte Less than or equal to quantity__lte=10

Membership Operators

Operator Description Example
in In list (comma-sep) status__in=active,pending
nin Not in list (comma-sep) status__nin=archived,deleted

Null Check Operators

Operator Description Example
is_null Is null deleted_at__is_null=true
is_not_null Is not null email__is_not_null=true

For is_null and is_not_null, the value is ignored. Only the presence of the parameter matters.

Pattern Matching Operators

Operator Description Example
like Pattern match (case-sensitive) title__like=%tutorial%
ilike Pattern match (case-insensitive) title__ilike=%tutorial%

Use % as a wildcard for zero or more characters and _ for a single character, following standard SQL LIKE syntax.

Sorting

Use the _sort parameter to order results by a field. Prefix the field name with - for descending order.

GET /v1/posts?_sort=created_at        # Ascending (oldest first)
GET /v1/posts?_sort=-created_at       # Descending (newest first)

Only fields marked as sortable: true in the resource definition (plus system fields id, created_at, and updated_at) can be used for sorting.

Pagination

Control the number of records returned and the starting offset with _limit and _offset.

Parameter Type Default Max Description
_limit integer 50 1000 Records per page
_offset integer 0 none Records to skip

Example: page 3 with 25 records per page:

GET /v1/posts?_limit=25&_offset=50

The response includes meta.total and pagination links so you can navigate between pages:

{
  "meta": {
    "total": 142
  },
  "links": {
    "self": "/v1/posts?page[offset]=50&page[limit]=25",
    "first": "/v1/posts?page[offset]=0&page[limit]=25",
    "prev": "/v1/posts?page[offset]=25&page[limit]=25",
    "next": "/v1/posts?page[offset]=75&page[limit]=25",
    "last": "/v1/posts?page[offset]=125&page[limit]=25"
  }
}

Field Selection

Use the fields parameter to return only specific fields. Pass a comma-separated list of field names.

GET /v1/posts?fields=id,title,created_at

This reduces payload size and can improve response times.

Reserved Query Parameters

The following parameter names are reserved and cannot be used as filter field names:

Parameter Purpose
_limit Pagination, records per page
_offset Pagination, records to skip
_sort Sort field and direction
fields Field selection (comma-separated)
events Event streaming configuration

Combining Parameters

All query parameters can be combined in a single request:

GET /v1/posts?status__eq=published&created_at__gte=2026-01-01&_sort=-created_at&_limit=25&_offset=0&fields=id,title,created_at

This retrieves published posts created in 2026 or later, sorted newest first, returning only id, title, and created_at, with 25 results per page.
⚡