From 85edd43b7ec2bfe1c57d1b2f07b545f5c4374392 Mon Sep 17 00:00:00 2001 From: Grey Date: Tue, 20 Oct 2026 14:30:37 -0400 Subject: [PATCH 1/3] update signatures list instructions & example to use cursor pagination --- .../authenticated_api/_signatures.md.erb | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/source/includes/authenticated_api/_signatures.md.erb b/source/includes/authenticated_api/_signatures.md.erb index 10e69b19c78..b99b3faba3d 100644 --- a/source/includes/authenticated_api/_signatures.md.erb +++ b/source/includes/authenticated_api/_signatures.md.erb @@ -330,10 +330,9 @@ Permanently deletes the signature with the specified ID. Note that this will dec } ], "meta": { - "current_page": 2, - "total_pages": 2, - "previous_page": 1, - "next_page": null + "next_since_id": 123, + "has_more": true, + "per_page": 25 } } ``` @@ -341,7 +340,8 @@ Permanently deletes the signature with the specified ID. Note that this will dec List the signatures that are part of a Petition. -<%= partial "includes/shared/pagination.md" %> +Pass the `since_id` parameter with a signature ID, and a `per_page` parameter to control the number of signatures returned per page. The default for the latter is 10 signatures per page, and the maximum is 100. +The response returns up to `per_page` signatures with IDs greater than `since_id` in ascending order by ID. To retrieve the first page, use `since_id=0`. Hash | Description --------- | ------- @@ -349,7 +349,13 @@ meta | pagination information petition | basic information about the petition signatures | an array of signature results -`GET /api/v1/petitions/no-taxes-on-tea/signatures?page=2` +The meta object includes: + +- `next_since_id`: the value to pass as `since_id` when requesting the next page. +- `has_more`: whether additional signatures are available. +- `per_page`: the requested number of signatures per page. + +`GET /api/v1/petitions/no-taxes-on-tea/signatures?since_id=123&per_page=25`
From b5ac69341e02937377af8c1540fe26027126b430 Mon Sep 17 00:00:00 2001 From: Grey Date: Tue, 20 Oct 2026 15:34:08 -0400 Subject: [PATCH 2/3] DRY cursor pagination instructions --- .../includes/authenticated_api/_cursor_pagination.md.erb | 9 +++++++++ source/includes/authenticated_api/_petitions.md.erb | 9 +-------- source/includes/authenticated_api/_signatures.md.erb | 9 +-------- 3 files changed, 11 insertions(+), 16 deletions(-) create mode 100644 source/includes/authenticated_api/_cursor_pagination.md.erb diff --git a/source/includes/authenticated_api/_cursor_pagination.md.erb b/source/includes/authenticated_api/_cursor_pagination.md.erb new file mode 100644 index 00000000000..f6772d8b286 --- /dev/null +++ b/source/includes/authenticated_api/_cursor_pagination.md.erb @@ -0,0 +1,9 @@ +Pass the `since_id` parameter with a <%= item_type_singular %> ID, and a `per_page` parameter to control the number of <%= item_type_plural %> returned per page. The default for the latter is 10 <%= item_type_plural %> per page, and the maximum is 100. + +The response returns up to `per_page` <%= item_type_plural %> with IDs greater than `since_id` in ascending order by ID. To retrieve the first page, use `since_id=0`. + +The meta object includes: + +- `next_since_id`: the value to pass as `since_id` when requesting the next page. +- `has_more`: whether additional <%= item_type_plural %> are available. +- `per_page`: the requested number of <%= item_type_plural %> per page. diff --git a/source/includes/authenticated_api/_petitions.md.erb b/source/includes/authenticated_api/_petitions.md.erb index b8a40ae09f1..30274d5fcb6 100644 --- a/source/includes/authenticated_api/_petitions.md.erb +++ b/source/includes/authenticated_api/_petitions.md.erb @@ -211,15 +211,8 @@ the petition `slug` is `save-our-library`. ``` Get a paginated list of all petitions, including petitions that are unlaunched or otherwise not visible to the public. Each petition includes the same data returned by the single-petition endpoint. -Pass the `since_id` parameter with a petition ID, and a `per_page` parameter to control the number of petitions returned per page. The default for the latter is 10 petitions per page, and the maximum is 100. -The response returns up to `per_page` petitions with IDs greater than `since_id` in ascending order by ID. To retrieve the first page, use `since_id=0`. - -The meta object includes: - -- `next_since_id`: the value to pass as `since_id` when requesting the next page. -- `has_more`: whether additional petitions are available. -- `per_page`: the requested number of petitions per page. +<%= partial "includes/authenticated_api/cursor_pagination.md.erb", locals: {item_type_singular: 'petition', item_type_plural: 'petitions'} %> `GET /api/v1/petitions?since_id=0` diff --git a/source/includes/authenticated_api/_signatures.md.erb b/source/includes/authenticated_api/_signatures.md.erb index b99b3faba3d..f53a38ae303 100644 --- a/source/includes/authenticated_api/_signatures.md.erb +++ b/source/includes/authenticated_api/_signatures.md.erb @@ -340,8 +340,7 @@ Permanently deletes the signature with the specified ID. Note that this will dec List the signatures that are part of a Petition. -Pass the `since_id` parameter with a signature ID, and a `per_page` parameter to control the number of signatures returned per page. The default for the latter is 10 signatures per page, and the maximum is 100. -The response returns up to `per_page` signatures with IDs greater than `since_id` in ascending order by ID. To retrieve the first page, use `since_id=0`. +<%= partial "includes/authenticated_api/cursor_pagination.md.erb", locals: {item_type_singular: 'signature', item_type_plural: 'signatures'} %> Hash | Description --------- | ------- @@ -349,12 +348,6 @@ meta | pagination information petition | basic information about the petition signatures | an array of signature results -The meta object includes: - -- `next_since_id`: the value to pass as `since_id` when requesting the next page. -- `has_more`: whether additional signatures are available. -- `per_page`: the requested number of signatures per page. - `GET /api/v1/petitions/no-taxes-on-tea/signatures?since_id=123&per_page=25` From 99539d98b796cdaa6e7c98d6fadb1028f57942e7 Mon Sep 17 00:00:00 2001 From: Grey Date: Tue, 20 Oct 2026 15:37:31 -0400 Subject: [PATCH 3/3] update pagination instructions for attendees too --- source/includes/authenticated_api/_attendees.md.erb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/includes/authenticated_api/_attendees.md.erb b/source/includes/authenticated_api/_attendees.md.erb index 8dbbd597e9d..7dca2f593f1 100644 --- a/source/includes/authenticated_api/_attendees.md.erb +++ b/source/includes/authenticated_api/_attendees.md.erb @@ -224,7 +224,7 @@ Permanently deletes the attendee with the specified ID. List the attendees that have RSVPed to an Event. -<%= partial "includes/shared/pagination.md" %> +<%= partial "includes/authenticated_api/cursor_pagination.md.erb", locals: {item_type_singular: 'attendee', item_type_plural: 'attendees'} %> Hash | Description ----------- | ----------- @@ -232,7 +232,7 @@ meta | pagination information event | basic information about the event attendees | an array of attendee results -`GET /api/v1/events/deliver-the-petition-to-the-wizard/attendees?page=2` +`GET /api/v1/events/deliver-the-petition-to-the-wizard/attendees?since_id=123&per_page=25`