Skip to content

Paging, filters and sorting

On this page we will detail the paging, filtering and sorting pattern.

Paging

In all query operations that return lists, the application provides a paging mechanism. There are two parameters: limit and offset. Both parameters define the block size of the results. This avoids excessive consumption of server and client resources, in addition to optimizing the visualization of information by the end user.

Query parameters

Parameter Description Value default
_limit Determines the number of records to be returned 50
_offset Position of the reference record, from which the next N records will be returned 0

Example:

GET /v1/orders?_offset=150&_limit=20

Response parameters

Parameter Description Value default
limit Returns the specific number of records 50
count Number of records that were returned on this page 0
max_limit Refers to the maximum value that can be used in the limit field 0

Response:

{
    "page": {
        "limit": 20,
        "offset": 150,
        "count": 1,
        "max_limit": 10
    }
}

In the above query, starting from record #151, the next 20 records will be returned.

For the demo we will set the default value to 50 and the maximum value to 200.

Example Result
/v1/orders?_offset=150&_limit=20 The next 20 records will be returned, starting from record #151
/v1/orders?_offset=0 The next 50 records will be returned, starting from the first record
/v1/orders?_offset=0&_limit=1 The first record will be returned.
/v1/orders?_offset=0&_limit=51 The next 51 records will be returned, starting from the first record
/v1/orders?_offset=0&_limit=200 The next 200 records will be returned, starting from the first record

Sorting

The application provides the possibility to sort the values ​​of the listings, in ascending and descending directions:

Identifier Sort Example
?_sort=field:asc Ascending GET /v1/orders?_sort=shipping.date:asc
?_sort=field:desc Descendant GET /v1/orders?_sort=shipping.date:desc

Note

If no sort is specified after the field name, an asc sort is applied.

Sorts with field combinations

More than one sort criteria can be specified in the same URL:

?_sort=field1:asc,field2:desc,field3:asc

When the criteria are combined, the sorting rule is applied one over the other, from left to right.

Filter

Researches

The application has mechanisms so that the collection can be consulted through search filters. These criteria are always expressed in the URL through query parameters.

Note

In this case, the application uses field names with all characters in lowercase.

Identifier Criterion Example
?field=value Exact value GET /v0/orders?branch.id=175&code=ABC
?field__like=value Partial value (like) GET /v0/orders?customer.name__like=Ana
?field__in=value_1,value_2,value_X List of values (in) GET /v0/orders?branch.id__in=175,215,830
?field__gt=value Greater than (>) GET /v0/orders?amount__gt=100
?field__gte=value Greater than or equal to (>=) GET /v0/orders?amount__gte=100
?field__lt=value Less than (<) GET /v0/orders?amount__lt=100
?field__lte=value Less than or equal to (=<) GET /v0/orders?amount__lte=100

Note

  • To make use of the between function, the application uses Greater than or Greater than and Less than or Less than or equal to.
  • The criteria are summed as an AND.

When the search involves fields that are modeled as objects in the body, the application references them through the path complete to the attribute - using the dot separator.

For example, for the following JSON body:

{
    "customer": {
        "id": 1000,
        "name": "..."
    },
    "branch": {
        "id": 595
    }
}

The search would look like this:

GET /v1/orders?customer.id=1000 & branch.id=595

Warning

Limitations with query parameters

The HTTP 1.1 RFC does not limit the number of characters in the URI, as can be seen from the links: https://tools.ietf.org/html/rfc2616#section-3.2.1
https://tools.ietf.org/html/rfc2068#section-3.2.2

When designing APIs, we suggest caution when using very long URIs. In general, very long URIs are indicative that your API may not adhere to industry standards. The application suggests modeling in some other way to conform to the REST standard.

In some cases, restrictions may be encountered on the web server due to security or fine configuration of performance reasons.In general parse can slow down the server.

Response:

{
    "meta": {
        "page": {
            "limit": 10,
            "offset": 0,
            "count": 1,
            "max_limit": 10
        },
        "links": {
            "previous": "/v0/orders?_limit=10&_offset=0",
            "self": "/v0/orders?_limit=10&_offset=10",
            "next": "/v0/orders?_limit=10&_offset=20"
        },
    },
    "results": [
        {
            "sku": "ABC1232fd",
            "channel": "magalu",
            "quantity": 1.5,
            "unit": "unit"
        }
    ]
}

The results field returns the expected data. The meta field returns information about the quantities of records found, where only the total field is optional. The filters applied in the query, return the field used as a filter, the operator used being represented by the names: eq, like, in, gt, gte, lt, lte and the value applied.

The collations identify the field and the collation (asc and desc) that was applied, and the Paging URLs, to get the next or previous records if they exist, as the URL itself that was consulted.