# Pagination

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](https://datatracker.ietf.org/doc/html/rfc5988#section-5). 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`.

## How to navigate through a paginated collection

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:


```http
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:


```http
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.


## Pagination parameters

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`.