Endpoints that return multiple objects paginate their responses to reduce the risk of overloading the server or the client. To retrieve all the data in the collection, the client will need to request subsequent pages.
Each endpoint with pagination will return a response with a Link header, as defined in RFC 5988. The header will contain two links: previous and next. previous will link to the page that immediately proceeds the current one, next will link to the page that succeeds it. If the current page is the first or last, the previous or next links respectively will be about:blank.
There are two pagination schemes currently in use in this API, but navigating through them is the same.
Begin by requesting the first page of the collection. The response will have a Link header that looks something like this:
Link: <about:blank>; rel="previous", <https://api.ev.energy/v2/vehicles?page_size=25&page_after=vhcl01HNARS42AVJN9QWQF6J52B7MB>; rel="next"Because we requested the first page, the previous link is about:blank; there are no earlier pages to get. This collection uses cursor-based pagination, so the next link is a URL which uses the page_after parameter to tell the server to give us the page that comes after vhcl01HNARS42AVJN9QWQF6J52B7MB, which is the last resource of the current page.
If we request the next link we will get a second page of vehicles. It will have its own Link header which can be used in exactly the same way.
The links also include a page_size parameter, which defaults to 25. This can be changed to increase or decrease the size of the page.
If the collection instead uses page number-based pagination, the header will look like this:
Link: <about:blank>; rel="previous", <https://api.ev.energy/v2/tariffs?page_size=25&page=2>; rel="next"However, client behaviour is the same, following the next and previous links to go forwards and back through the collection. This pagination scheme is used for endpoints which are not sorted by a unique value.
In general, avoid manually constructing pagination URLs and use those provided by the Link header. This will make your integration more robust to future changes in the API.
There are three query parameters used to control pagination:
page_size: The number of items to return in a single page. Must be between 1 and 100. Defaults to 25.page_after: Return only resources that were created after the value, which must be a valid ID for the current collection.page_before: Return only resource that were created immediately before the value, which must be a valid ID for the current collection.page: Return the specified numbered page. Must be above 0. If you attempt to request a page that does not exist (such as page 10 when there are only 3 pages of results) a 404 response will be generated.
If both page_before and Page_after are included, the page_before value will be ignored, and page will never be used at the same time as page_before or page_after.