From 22ee2fa485a97221a65c1e6969a62b5c52bd5869 Mon Sep 17 00:00:00 2001 From: "Erik Trapin (ecoologic)" Date: Fri, 3 Nov 2023 15:11:08 +1000 Subject: [PATCH] CBP Doc --- README.md | 24 ++++++++-- UPGRADE_GUIDE.md | 47 ++++++++++++++----- .../Traits/Utility/Pagination/CbpStrategy.php | 4 +- 3 files changed, 59 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 94c348ec..2dc64ae8 100755 --- a/README.md +++ b/README.md @@ -132,14 +132,30 @@ There are two ways to do pagination in the Zendesk API, **CBP (Cursor Based Pagi The use of the correct pagination is encapsulated using the iterator pattern, which allows you to retrieve all resources in all pages, without having to deal with pagination at all: ```php -$ticketsIterator = $client->tickets()->iterator(); +$iterator = $client->tickets()->iterator(); -foreach ($ticketsIterator as $ticket) { - process($ticket); // Your implementation +foreach ($iterator as $ticket) { + echo($ticket->id . " "); } ``` -If you want to customise your sort order, please refer to the sorting section in the documentation ([Tickets, for example](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#sorting)). If you are upgrading from OBP, please refer to [the upgrade guide](./UPGRADE_GUIDE.md). +If you want a specific sort order, please refer to the sorting section in the documentation ([Tickets, for example](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#sorting)). If you are upgrading from OBP, please refer to [the upgrade guide](./UPGRADE_GUIDE.md). + +##### Iterator with params example + +```php +$params = ['my' => 'param1', 'extra' => 'param2']; +$iterator = $client->tickets()->iterator($params); + +foreach ($iterator as $ticket) { + echo($ticket->id . " "); +} +``` + +* Change page size with: `$params = ['page[size]' => 5];` +* Change sorting with: `$params = ['sort' => '-updated_at'];` + * Refer to the docs for details, including allowed sort fields +* Combine everything: `$params = ['page[size]' => 2, 'sort' => 'updated_at', 'extra' => 'param'];` #### Find All using CBP (fine) diff --git a/UPGRADE_GUIDE.md b/UPGRADE_GUIDE.md index a3a37722..f31521bc 100644 --- a/UPGRADE_GUIDE.md +++ b/UPGRADE_GUIDE.md @@ -1,15 +1,39 @@ # Upgrade guide -TODO: review and provide examples. - -## Gotchas moving from OBP to CBP - -### Useful links +## Useful links * [Pagination](https://developer.zendesk.com/api-reference/introduction/pagination) * [Ticketing sorting](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#sorting) -### CBP ordering +## Basics + +**OBP (Offset Based Pagination)** is quite inefficient, and increasingly so the higher the page you fetch. Switching to **CBP (Cursor Based Pagination)** will improve your application performance. OBP will eventually be deprecated. + +When in OBP you request page 100, the DB will need to index all 100 pages of records before it can load the rows for the page you requested. + +CBP works based on a cursors, so if the order is `id`, 10 elements per page and the last item on your page is 111, the response includes a link to the next page "next 10 elements after id 111", so no index is needed. + +URL example: + +* OBP: https://{subdomain}.zendesk.com/api/v2/tickets?sort_order=desc&sort_by=updated_at&per_page=2 +* CBP: https://{subdomain}.zendesk.com/api/v2/tickets?sort=-updated_at&page[size]=2 + +## The new iterator + +Your best solution to implement CBP is to use the newly provided iterator on your resources, for example: + +```php +$params = ['my' => 'param1', 'extra' => 'param2']; +$iterator = $client->tickets()->iterator($params); + +foreach ($iterator as $ticket) { + echo($ticket->id . " "); +} +``` + +This will choose the right type of pagination and adapt your parameters for pagination and ordering to work with CBP. + +## CBP ordering When moving from OBP to CBP sorting params change as well: @@ -21,7 +45,7 @@ Ticket example: * OBP: https://{subdomain}.zendesk.com/api/v2/tickets?sort_order=desc&sort_by=updated_at&per_page=2 * CBP: https://{subdomain}.zendesk.com/api/v2/tickets?sort=-updated_at&page[size]=2 -However, the list of attributes you can sort by is longer in OBP: +However, the list of **attributes you can sort by might also change** with the pagination type: https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#sorting @@ -30,8 +54,8 @@ https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#sorting Example: -* OBP: https://{subdomain}.zendesk.com/api/v2/tickets?sort_order=desc&sort_by=assignee.name&per_page=2 HTTP 200, works -* CBP: https://{subdomain}.zendesk.com/api/v2/tickets?sort=assignee.name&page[size]=2 HTTP 400 +* OBP: https://{subdomain}.zendesk.com/api/v2/tickets?sort_order=desc&sort_by=assignee.name&per_page=2 `HTTP 200`, works +* CBP: https://{subdomain}.zendesk.com/api/v2/tickets?sort=assignee.name&page[size]=2 `HTTP 400` ```json { @@ -40,7 +64,8 @@ Example: } ``` -TODO: confirm. If this is your situation, you need to change sorting order to a supported one. -### +## Parallel requests + +If you are fetching multiple pages in parallel using OBP, you need to refactor to a serial execution, and fetch one page at a time. diff --git a/src/Zendesk/API/Traits/Utility/Pagination/CbpStrategy.php b/src/Zendesk/API/Traits/Utility/Pagination/CbpStrategy.php index c1e5213f..92bfa538 100644 --- a/src/Zendesk/API/Traits/Utility/Pagination/CbpStrategy.php +++ b/src/Zendesk/API/Traits/Utility/Pagination/CbpStrategy.php @@ -10,7 +10,6 @@ class CbpStrategy extends AbstractStrategy { private $afterCursor = null; private $started = false; - private $sortParams; public function page($getPageFn) { @@ -36,6 +35,9 @@ public function params() * The params that are needed to ordering in CBP (eg: ["sort" => "-age"]) * If OBP params are passed, they are converted to CBP * + * OBP: https://{subdomain}.zendesk.com/api/v2/tickets?sort_order=desc&sort_by=updated_at&per_page=2 + * CBP: https://{subdomain}.zendesk.com/api/v2/tickets?sort=-updated_at&page[size]=2 + * * @return array all params with CBP sorting order */ private function sortParams()