As we've recently discovered, a bug in the implementation of the "get_next_page" functions in this library meant any specific filters used while getting pages for a given resource were not being preserved and carried forward (e.g. the type of report, a specific tracking code for trackers, "purchased" filter for shipments).
This PR redesigned the underlying implementation of the "get_next_page" functions to be more explicit and account for minor inconsistencies endpoint-to-endpoint by relying on a hidden "_filters" key that will carry necessary metadata about parameters and filters used for each "all" and "get_next_page" call for easy reference behind the scenes when retrieving the next page of a paginated collection. From an end-user perspective, this means they will not need to always pass in, e.g., the "purchased" filter for each page request of shipments, or the type of report for each page request of reports. Whatever filters were used to retrieve the first page of a paginated collection will be reused automatically behind-the-scenes when retrieving each subsequent page. ("page_size" is still on a per-page basis, and filters can be overridden with optional parameters if necessary). This more closely follows the design of pagination as implemented in the Java and .NET library, which were the original models for these functions.
This PR does not change the majority of the end-user experience or public function signatures. As demonstrated by the minor changes to the unit tests and the lack of need to re-record any cassettes, this implementation change does not alter the shape or workflow as it previously was.
The only "breaking changes" include:
"get_next_page" for the Batch service now throws a NotImplementedError, as there is a known bug with batch pagination server-side, and this function should not have been available in the first place.
"get_next_page" for the Order service now throws a NotImplementedError, as order pagination does not exist server-side, and this function should not have been available in the first place. There was not an "all" function for Orders in the first place, so it's unclear how an end-user would have been able to retrieve the first page to use with this function anyhow.
Testing
All pagination unit tests have had assertions added to verify the new "filters" are being passed forward as expected, and that the implementation changes do not alter the existing end-user experience
Only the "referral customer get next page" cassette needed to be re-recorded, as new server-side data allowed for a second page and therefore a second HTTP request/response to be recorded.
Pull Request Type
Please select the option(s) that are relevant to this PR.
[x] Bug fix (non-breaking change which fixes an issue)
[ ] New feature (non-breaking change which adds functionality)
[x] Breaking change (fix or feature that would cause existing functionality to not work as expected)
[ ] Improvement (fixing a typo, updating readme, renaming a variable name, etc)
Description
As we've recently discovered, a bug in the implementation of the "get_next_page" functions in this library meant any specific filters used while getting pages for a given resource were not being preserved and carried forward (e.g. the type of report, a specific tracking code for trackers, "purchased" filter for shipments).
This PR redesigned the underlying implementation of the "get_next_page" functions to be more explicit and account for minor inconsistencies endpoint-to-endpoint by relying on a hidden "_filters" key that will carry necessary metadata about parameters and filters used for each "all" and "get_next_page" call for easy reference behind the scenes when retrieving the next page of a paginated collection. From an end-user perspective, this means they will not need to always pass in, e.g., the "purchased" filter for each page request of shipments, or the type of report for each page request of reports. Whatever filters were used to retrieve the first page of a paginated collection will be reused automatically behind-the-scenes when retrieving each subsequent page. ("page_size" is still on a per-page basis, and filters can be overridden with optional parameters if necessary). This more closely follows the design of pagination as implemented in the Java and .NET library, which were the original models for these functions.
This PR does not change the majority of the end-user experience or public function signatures. As demonstrated by the minor changes to the unit tests and the lack of need to re-record any cassettes, this implementation change does not alter the shape or workflow as it previously was.
The only "breaking changes" include:
"get_next_page" for the Batch service now throws aNotImplementedError, as there is a known bug with batch pagination server-side, and this function should not have been available in the first place.NotImplementedError, as order pagination does not exist server-side, and this function should not have been available in the first place. There was not an "all" function for Orders in the first place, so it's unclear how an end-user would have been able to retrieve the first page to use with this function anyhow.Testing
Pull Request Type
Please select the option(s) that are relevant to this PR.