Pagination concepts

This page should give you a short introduction into the pagination concepts used in this API.

Offset based pagination

The API offers offset based pagination. Offset pagination will accept two parameters in the URL page[limit] and page[offset].

The parameter page[limit] will define how big the page will get at maximum. A result set bigger than page[limit] will result in multiple pages. Note that the system has upper limits (usually 500 but this might differ between the endpoints). If you choose a page limit bigger than this upper limit, the system will automatically set it back to its maximum value. E.g. if you choose a limit of 1000 and the endpoint allows only 500 entries at maximum, you will only see 500 entries on this page. You can see the page limit in the pagination response limit field.

The parameter page[offset] will allow you to go further in the pages. Usually you will add the limit to the last offset and continue you to scroll through the pages.

The response contains also links which the client can use to page through the pages. As long as there are further pages you will find a link with the name next which can be used to fetch the next page. You can also browse backwards with the link prev.

A sample pagination URL: https://mandant.beenergised.cloud/api/cpoapi/v1/maintenance_windows/? page[limit]=500&page[offset]=200

A response might look like (without data):

"data": [
    {
        "type": "maintenance_windows",
        "id": "1234",
        "attributes": {
            "cpId": "622d625f-ebda-434d-b821-feee9ad1bfaa",
            "connectorId": null,
            "comment": "Repair the station.",
            "startDate": "2021-02-17T07:00:00.000Z",
            "endDate": "2021-02-17T17:00:00.000Z"
        }
    }
],
"meta": {
    "pagination": {
        "total": 12345,
        "offset": 200,
        "limit": 500,
        "lastPage": false
    }
},
"links": {
    "current": "https://mandant.beenergised.cloud/api/cpoapi/v1/maintenance_windows/?page%5Blimit%5D=500&page%5Boffset%5D=200",
    "next": "https://mandant.beenergised.cloud/api/cpoapi/v1/maintenance_windows/?page%5Blimit%5D=500&page%5Boffset%5D=700"
}

Page based pagination

The API offers also paged based pagination. Paged based pagination will accept two parameters in the URL page[pageSize] and page[pageNr].

The parameter page[pageSize] will define how big the page will get at maximum. A result set bigger than page[pageSize] will result in multiple pages. Note that the system has upper limits (usually 500 but this might differ between the endpoints). If you choose a page size bigger than this upper limit, the system will automatically set it back to its maximum value. E.g. if you choose a limit of 1000 and the endpoint allows only 500 entries at maximum, you will only see 500 entries on this page. You can see the page limit in the pagination response limit field.

The parameter page[pageNr] will allow you to go further in the pages. The next page is increasing the pageNr with the next size.

The response contains also links which the client can use to page through the pages. As long as there are further pages you will find a link with the name next which can be used to fetch the next page. You can also browse backwards with the link prev.

A sample pagination URL: https://mandant.beenergised.cloud/api/cpoapi/v1/connectors/ aa7065d6-09c2-44f6-bab8-335fe3d0d0ab/meter_values ?filters[from]=2022-11-24T07:41:00.000Z& filters[to]=2022-11-31T07:41:00.000Z&filters[measurand]=SoC& page[pageSize]=1&page[pageNr]=2

A response might look like (without data):

"data": [
    {
        "type": "meter_value",
        "id": "1",
        "attributes": {
            "context": "Transaction.End",
            "cpUuid": "1234567-9914-4aca-b49d-b8b36295c370",
            "connectorUuid": "1234567-09c2-44f6-bab8-335fe3d0d0ab",
            "location": "Outlet",
            "measurand": "SoC",
            "timestamp": "2022-11-30T15:42:55.000Z",
            "phase": null,
            "value": 36
        }
    }
],
"meta": {
    "pagination": {
        "pageNr": 1,
        "size": 500,
        "totalPages": 1
    }
},
"links": {
    "current": "https://mandant.beenergised.cloud/api/cpoapi/v1/connectors/1234567-09c2-44f6-bab8-335fe3d0d0ab/meter_values?filters%5Bfrom%5D=2022-11-24T07%3A41%3A00.000Z&filters%5Bto%5D=2022-11-31T07%3A41%3A00.000Z&filters%5Bmeasurand%5D=SoC&page%5BpageSize%5D=1&page%5BpageNr%5D=2",
    "next": "https://mandant.beenergised.cloud.localhost/api/cpoapi/v1/connectors/1234567-09c2-44f6-bab8-335fe3d0d0ab/meter_values?filters%5Bfrom%5D=2022-11-24T07%3A41%3A00.000Z&filters%5Bto%5D=2022-11-31T07%3A41%3A00.000Z&filters%5Bmeasurand%5D=SoC&page%5BpageSize%5D=1&page%5BpageNr%5D=3",
    "prev": "https://mandant.beenergised.cloud.localhost/api/cpoapi/v1/connectors/1234567-09c2-44f6-bab8-335fe3d0d0ab/meter_values?filters%5Bfrom%5D=2022-11-24T07%3A41%3A00.000Z&filters%5Bto%5D=2022-11-31T07%3A41%3A00.000Z&filters%5Bmeasurand%5D=SoC&page%5BpageSize%5D=1&page%5BpageNr%5D=1"
}