Pagination, sorting and filtering
Pagination
Introduction
Three parameters allow you to manage the paginated resource display.
The parameters are
- limit: allows you to limit the number of elements returned
- offset: allows you to ignore the first n elements of the list
- total: allows you to retrieve the total number of resources if indeed the request had not limited the number of resources returned. It is therefore useful in the framework of using a limit for pagination. (the default is false). This feature uses a lot of resources. It is recommended that it not be activated in the case there is no pagination.
Example 1: Limiting results
Retrieving only 20 resources and the total number of resources if the result were limited to 20 resources
GET /rest/ressource HTTP/1.1 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2… limit=20&total=true |
with Curl
curl
-X GET |
Example 2: Pagination
Retrieving 10 resources, leaving aside the first 20. This boils down to reading the 3rd page knowing that each page lists 10 resources.
GET /rest/ressource HTTP/1.1 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2… limit=10&offset=20 |
Sorting
Introduction
The sort parameter allows you to order the list of resources returned according to one of the attributes of the resource concerned. This parameter is comprised of two elements separated by a space:
- The name of the attribute according to which you want to order the list
- The sorting order, ascending order (ASC) or descending order (DESC)
Example
Sorting a list of resources in descending order according to the id of this resource:
GET /rest/ressource HTTP/1.1 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2… sort=id%20DESC |
with Curl
curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ" -d sort=id DESC https://api.messengeo.net/rest/ressource |
Limiting the list of attributes returned per resource
Introduction
It is possible to limit the list of attributes of the resources returned. In other words, this entails returning incomplete resources in order to focus on the attributes that are really necessary for the client that generated the call.
This makes it possible to save both bandwidth and processing on the server side. Indeed, certain attributes are calculated at the time of the call and not retrieving them makes it possible to reduce the request time.
The parameter that allows you to define the attributed return is called properties.
For each resource, a list of attributes returned by default (if the properties parameter is not defined) is imposed. An alias called DEFAULT makes it possible to specify that you want to retrieve the attributes by default + another or – another.
Example 1
Retrieving only the is and the name of each resource
GET /rest/ressource HTTP/1.1 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2… properties=id,name |
with Curl
curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ" -d properties=id,name https://api.messengeo.net/rest/ressource |
Example 2
Retrieving the attributes returned by default except the id
GET /rest/ressource HTTP/1.1 Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpZCI6ImYyMzE2… properties=DEFAULT,-id |
with Curl
curl -X GET -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ" -d properties=DEFAULT,-id https://api.messengeo.net/rest/ressource |