From 61e73a853f672aed649a7324ce566c89620205cd Mon Sep 17 00:00:00 2001 From: anero Date: Tue, 1 Sep 2026 15:45:54 -0300 Subject: [PATCH 1/3] Update docs for authenticated API endpoint for retrieving the petitions list --- .../includes/authenticated_api/_petitions.md.erb | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/source/includes/authenticated_api/_petitions.md.erb b/source/includes/authenticated_api/_petitions.md.erb index 20c4915caaf..85476188aca 100644 --- a/source/includes/authenticated_api/_petitions.md.erb +++ b/source/includes/authenticated_api/_petitions.md.erb @@ -182,7 +182,7 @@ the petition `slug` is `save-our-library`. ### List -> GET response body +> GET response body for cursor-based pagination ```json { @@ -203,17 +203,21 @@ the petition `slug` is `save-our-library`. ], "meta": { - "current_page": 1, - "total_pages": 12, - "previous_page": null, - "next_page": 2 + "next_since_id": 134, + "has_more": true, + "per_page": 10 } } ``` Get a paginated list of all petitions, including ones that are unlaunched or otherwise not visible to the public. Includes all the same data as the single-petition endpoint for each petition. -<%= partial "includes/shared/pagination.md" %> +This is a paginated response. You can use two different mechanisms to advance to the next page of results: + +- Using a cursor-based approach, passing the `since_id` parameter, which accepts a petition ID integer. The response will include all petitions with IDs greater than the `since_id` value and the `meta` object will include the `next_since_id`, `has_more` and `total_count` values. When using this pagination mechanism you can also pass a `per_page` parameter to change the limit of the number of petitions returned per page. The default is 10, and the maximum is 100. To retrieve the first page use `since_id=0`. +- Passing the `page` parameter, which accepts a page number integer. The response includes a `meta` object with the `current_page`, `total_pages`, `previous_page` and `next_page` values. + +By default we use the non cursor-based mechanism, returning the first page of results. `GET /api/v1/petitions?page=1` From 11cbcbc30f7dc5f5f6985a02c28be6d79cb55f78 Mon Sep 17 00:00:00 2001 From: anero Date: Tue, 1 Sep 2026 15:46:22 -0300 Subject: [PATCH 2/3] Updated SQL script with tables schema --- source/data/tables.sql | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/data/tables.sql b/source/data/tables.sql index c07659ef6d8..025e2bec9bc 100644 --- a/source/data/tables.sql +++ b/source/data/tables.sql @@ -41,7 +41,7 @@ CREATE TABLE data_processing_consents ("id" bigint, "data_processing_consentable DROP TABLE IF EXISTS drip_email_preferences; CREATE TABLE drip_email_preferences ("id" integer, "organisation_id" integer, "slug" CHARACTER VARYING(max), "enabled" boolean, "created_at" timestamp without time zone, "updated_at" timestamp without time zone); DROP TABLE IF EXISTS efforts; -CREATE TABLE efforts ("id" integer, "organisation_id" integer, "slug" CHARACTER VARYING(max), "title_default" CHARACTER VARYING(max), "who_default" CHARACTER VARYING(max), "created_at" timestamp without time zone, "updated_at" timestamp without time zone, "ask_for_location" boolean, "effort_type" CHARACTER VARYING(max), "distance_limit" integer, "prompt_edit_individual_petition" boolean, "featured" boolean, "image_default_file_name" CHARACTER VARYING(max), "image_default_content_type" CHARACTER VARYING(max), "image_default_file_size" integer, "image_default_updated_at" timestamp without time zone, "target_collection_id" integer, "settings" CHARACTER VARYING(max), "custom_goal" integer, "global_signature_count_add_amount" integer, "search_method" CHARACTER VARYING(max), "launched" boolean, "wizard_fields" CHARACTER VARYING(max), "search_kind" CHARACTER VARYING(max), "objective_collection_id" integer, "theme_id" bigint, "external_ids" CHARACTER VARYING(max)); +CREATE TABLE efforts ("id" integer, "organisation_id" integer, "slug" CHARACTER VARYING(max), "title_default" CHARACTER VARYING(max), "who_default" CHARACTER VARYING(max), "created_at" timestamp without time zone, "updated_at" timestamp without time zone, "ask_for_location" boolean, "effort_type" CHARACTER VARYING(max), "distance_limit" integer, "prompt_edit_individual_petition" boolean, "featured" boolean, "target_collection_id" integer, "settings" CHARACTER VARYING(max), "custom_goal" integer, "global_signature_count_add_amount" integer, "search_method" CHARACTER VARYING(max), "launched" boolean, "wizard_fields" CHARACTER VARYING(max), "search_kind" CHARACTER VARYING(max), "objective_collection_id" integer, "theme_id" bigint, "external_ids" CHARACTER VARYING(max)); DROP TABLE IF EXISTS email_opt_in_types; CREATE TABLE email_opt_in_types ("id" bigint, "organisation_id" bigint, "kind" CHARACTER VARYING(max), "mailable" boolean, "active" boolean, "created_at" timestamp without time zone, "updated_at" timestamp without time zone, "context" CHARACTER VARYING(max), "external_id" CHARACTER VARYING(max), "content_settings" CHARACTER VARYING(max)); DROP TABLE IF EXISTS email_opt_in_uploads; From 8f8a8140abcaf2ef70c5910cced060926ba763f4 Mon Sep 17 00:00:00 2001 From: anero Date: Tue, 1 Sep 2026 17:42:00 -0300 Subject: [PATCH 3/3] Copy edit --- .../authenticated_api/_petitions.md.erb | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/source/includes/authenticated_api/_petitions.md.erb b/source/includes/authenticated_api/_petitions.md.erb index 85476188aca..f01ad3daa66 100644 --- a/source/includes/authenticated_api/_petitions.md.erb +++ b/source/includes/authenticated_api/_petitions.md.erb @@ -210,16 +210,26 @@ the petition `slug` is `save-our-library`. } ``` -Get a paginated list of all petitions, including ones that are unlaunched or otherwise not visible to the public. Includes all the same data as the single-petition endpoint for each petition. +Get a paginated list of all petitions, including petitions that are unlaunched or otherwise not visible to the public. Each petition contains the same data returned by the single-petition endpoint. -This is a paginated response. You can use two different mechanisms to advance to the next page of results: +This endpoint supports two pagination mechanisms: -- Using a cursor-based approach, passing the `since_id` parameter, which accepts a petition ID integer. The response will include all petitions with IDs greater than the `since_id` value and the `meta` object will include the `next_since_id`, `has_more` and `total_count` values. When using this pagination mechanism you can also pass a `per_page` parameter to change the limit of the number of petitions returned per page. The default is 10, and the maximum is 100. To retrieve the first page use `since_id=0`. -- Passing the `page` parameter, which accepts a page number integer. The response includes a `meta` object with the `current_page`, `total_pages`, `previous_page` and `next_page` values. +- **Cursor-based pagination (recommended):** Pass the `since_id` parameter with a petition ID. The response returns up to `per_page` petitions with IDs greater than `since_id`. To retrieve the first page, use `since_id=0`. Petitions are returned in ascending order by ID. -By default we use the non cursor-based mechanism, returning the first page of results. + 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 number of petitions requested per page. + - `total_count`: the total number of petitions. -`GET /api/v1/petitions?page=1` + Use `per_page` to control the number of petitions returned per page. The default is 10 and the maximum is 100. + +- **Page-number pagination:** Pass the `page` parameter with the page number to retrieve. The meta object includes `current_page`, `total_pages`, `previous_page`, and `next_page`. + +The cursor-based approach is preferred as it offers better performance and allows retrieving larger result sets by using the `per_page` parameter. +For backward compatibility, we use by default the page number mechanism for requests not including the `since_id` or `page` parameters, and we return the first page of results. + +`GET /api/v1/petitions?since_id=0`