-
Notifications
You must be signed in to change notification settings - Fork 259
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add CbpStrategy accepting OBP params #517
Changes from 3 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,90 @@ | ||
# Upgrade guide | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There's a little duplication in the info below, but I think it's worth giving a TLDR summary. |
||
|
||
## Useful links | ||
|
||
* [Pagination](https://developer.zendesk.com/api-reference/introduction/pagination) | ||
* [Ticketing sorting](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#sorting) | ||
|
||
## CBP 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 subject to limits. | ||
Zendesk-NathanBellette marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
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. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Should we rephrase this? Maybe something like:
|
||
|
||
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", and only your page is indexed before the rows are fetched. | ||
|
||
## API calls | ||
|
||
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 | ||
|
||
### CBP ordering | ||
|
||
When moving from OBP to CBP sorting params change as well: | ||
|
||
* From: `?sort_name=updated_at&sort_order=desc` | ||
* To: `sort=-updated_at` | ||
|
||
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 might also change** with the pagination type: | ||
|
||
https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/#sorting | ||
|
||
* OBP: `"assignee", "assignee.name", "created_at", "group", "id", "locale", "requester"` | ||
* CBP: `"updated_at", "id", "status"` | ||
|
||
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` | ||
|
||
```json | ||
{ | ||
"error": "InvalidPaginationParameter", | ||
"description": "sort is not valid" | ||
} | ||
``` | ||
|
||
If this is your situation, **you need to change sorting order** to a supported one. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Possibly change this to:
|
||
|
||
## The new iterator | ||
|
||
Your best solution to implement CBP is to use the newly provided iterator on your resources, for example: | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Nitpickiest nitpick. I
|
||
|
||
```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. | ||
|
||
##### 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'];` | ||
|
||
|
||
## 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. |
Original file line number | Diff line number | Diff line change |
---|---|---|
|
@@ -11,20 +11,65 @@ class CbpStrategy extends AbstractStrategy | |
private $afterCursor = null; | ||
private $started = false; | ||
|
||
public function getPage($pageFn) | ||
public function page($getPageFn) | ||
{ | ||
$this->started = true; | ||
$params = ['page[size]' => $this->pageSize]; | ||
if ($this->afterCursor) { | ||
$params['page[after]'] = $this->afterCursor; | ||
} | ||
$response = $pageFn($params); | ||
|
||
$response = $getPageFn(); | ||
$this->afterCursor = $response->meta->has_more ? $response->meta->after_cursor : null; | ||
|
||
return $response->{$this->resourcesKey}; | ||
} | ||
|
||
public function shouldGetPage($position) { | ||
return !$this->started || $this->afterCursor; | ||
} | ||
|
||
public function params() | ||
{ | ||
$result = array_merge($this->params, $this->paginationParams(), $this->sortParams()); | ||
$result = $this->unsetObpParams($result); | ||
|
||
return $result; | ||
} | ||
/** | ||
* 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() | ||
{ | ||
if (isset($this->params['sort_by']) && !isset($this->params['sort'])) { | ||
$direction = (isset($this->params['sort_order']) && strtolower($this->params['sort_order']) === 'desc') ? '-' : ''; | ||
return array_merge($this->params, ['sort' => $direction . $this->params['sort_by']]); | ||
} else { | ||
return []; | ||
} | ||
} | ||
/** | ||
* The params that are needed to for pagination (eg: ["page[size]" => "100"]) | ||
* If OBP params are passed, they are converted to CBP | ||
* | ||
* @return array all params with CBP sorting order | ||
*/ | ||
private function paginationParams() | ||
{ | ||
$result = isset($this->afterCursor) ? ['page[after]' => $this->afterCursor] : []; | ||
|
||
return array_merge(['page[size]' => $this->pageSize()], $result); | ||
} | ||
|
||
private function unsetObpParams($params) | ||
{ | ||
unset( | ||
$params['page'], | ||
$params['per_page'], | ||
$params['sort_by'], | ||
$params['sort_order'] | ||
); | ||
return $params; | ||
} | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. so now the CbpStrategy knows a lot about OBP. I thought of extracting it, and I did, |
||
} |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I now prefer code that is fully testable, without having to define
process