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…
Host: api.messengeo.net
Content-Type: application/x-www-form-urlencoded

limit=20&total=true

with Curl

curl

 

-X GET
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"
-d limit=20
-d total=true
https://api.messengeo.net/rest/ressource

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…
Host: api.messengeo.net
Content-Type: application/x-www-form-urlencoded

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…
Host: api.messengeo.net
Content-Type: application/x-www-form-urlencoded

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…
Host: api.messengeo.net
Content-Type: application/x-www-form-urlencoded

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…
Host: api.messengeo.net
Content-Type: application/x-www-form-urlencoded

properties=DEFAULT,-id

with Curl

curl
-X GET
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbG...ccOqbVow8xOQyQ"
-d properties=DEFAULT,-id
https://api.messengeo.net/rest/ressource