Update docs for petitions list

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;

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,19 +203,33 @@ 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.
+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.
 
-<%= partial "includes/shared/pagination.md" %>
+This endpoint supports two pagination mechanisms:
 
-`GET /api/v1/petitions?page=1`
+- **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.
+
+    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.
+
+    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`
 
 <div></div>