First, you will want to import the CursorPaginator
class and return a new anonymous class that extends Saloon's CursorPaginator
. This class expects the connector and request to be passed in via the constructor arguments.
You don't need to use an anonymous class if it doesn't fit your code style. It is recommended to reduce the number of classes, but you can create your own pagination class that extends the base paginator if you prefer.
After you have defined your paginator class, you will be required to define three protected methods which are used to power the paginator. These methods are:
getNextCursor - This method is used to find the next cursor from the response. This method must return either an integer or a string. The next cursor is used in the next request to get a different page.
isLastPage - This method is used to tell the paginator when to stop processing. Here you can use the response class provided to determine if you are on the last page. Some APIs may provide metadata like remaining results or next page URLs which you can use to check if you are on the last page. Additionally, Saloon has a few properties that can be used to determine if you are on the last page.
getPageItems - This method is used to return the array of results inside of each page. This is used when using the items
or collect
method on your paginator class.
Let's implement these three methods on our paginator and dive into how it works.
Let's assume in this hypothetical example that the API provides a next_cursor
property in the JSON response. We'll return the value of this property in the getNextCursor
method. After that, we need to tell Saloon when to stop paginating. We'll use the same next_cursor
property again. If it's null, we know that there isn't another page to look up. There are various other ways of knowing if you are on the last page, so it's best to fully understand your API's pagination.
To get the page items, we'll use the json
method on the response to access the items
array from the body.
The third-party API you are integrating with may require you to define a page size (per page) on your requests, or you may want to set a default page size used for every request. You can set this default page size as a property on the paginator class.
You may also use the setPerPageLimit
method on an instantiated paginator if you want to configure it on the fly. You must set this before iterating over the paginator.
The CursorPaginator will apply pagination by sending two query parameters:
cursor
per_page
This assumption might not be the way your third-party API works. You can really easily change this by extending the applyPagination
method. For example, let's say our API expects a "pageCursor" and a "pageSize" instead. We can simply extend the applyPagination
method and change the keys. You can apply the pagination in whichever the API requires.
We previously mentioned that the CursorPaginator class provides a few methods that can be used to help with last-page calculation. These methods are:
totalResults - An integer which will return the total number of items returned. This can be used to check if it's equal to the number of total results in the list.
page - An integer which will return the current page that the paginator is currently on.
After configuring your paginator, head back to the section of the documentation.