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:
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:
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:
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 usesGreater than
orGreater than
andLess than
orLess 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:
The search would look like this:
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.