Skip to content

Commit 3a3f8e1

Browse files
committed
Clarify breaking change rules around pagination
(In particular, that adding pagination breaks client libraries too.) Fixes #1357.
1 parent 783b844 commit 3a3f8e1

2 files changed

Lines changed: 10 additions & 2 deletions

File tree

aip/general/0158.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -159,6 +159,12 @@ now is only getting the first 50 (and does not know to advance pagination).
159159
Even if the API set a higher default limit, such as 100, the user's collection
160160
could grow, and _then_ the code would break.
161161

162+
Additionally, [client libraries implement automatic
163+
pagination](../client-libraries/4233.md), typically representing paginated
164+
RPCs using different method signatures to unpaginated ones. This means that
165+
adding pagination to a previously-unpaginated method causes a breaking change
166+
in those libraries.
167+
162168
For this reason, it is important to always add pagination to RPCs returning
163169
collections _up front_; they are consistently important, and they can not be
164170
added later without causing problems for existing users.
@@ -172,6 +178,8 @@ paginate) is reasonable for initially-small collections.
172178

173179
## Changelog
174180

181+
- **2020-05-24**: Clarified that adding pagination breaks client
182+
libraries.
175183
- **2020-05-13**: Added guidance for skipping results.
176184
- **2020-08-24**: Clarified that responses are not streaming responses.
177185
- **2020-06-24**: Clarified that page size is always optional for users.

aip/general/0180.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -258,7 +258,7 @@ version.
258258
[aip-158]: ./0158.md
259259
[aip-181]: ./0181.md
260260
[aip-203]: ./0203.md
261-
[aip-4231]: ./client-libraries/4231.md
262-
[aip-4232]: ./client-libraries/4232.md
261+
[aip-4231]: ../client-libraries/4231.md
262+
[aip-4232]: ../client-libraries/4232.md
263263
[ec2]: https://aws.amazon.com/blogs/aws/theyre-here-longer-ec2-resource-ids-now-available/
264264
<!-- prettier-ignore-end -->

0 commit comments

Comments
 (0)