Update docs for petitions list

[anero]

This updates the docs for the petitions list API endpoint for the changes made on https://github.com/controlshift/agra/pull/14252.
I intentionally listed the cursor-based approach first since that has better performance on our end and is the option we'd like the consumers to use.

[lavaturtle]

👍

[woodhull]

I wonder if we should remove the old mechanism from the docs entirely.

I kind of want to retire the old pagination and other sources of perf pathology like this so we can save thousands of dollars by shrinking the database.

I also wonder what other API endpoints have the same pagination performance footgun. Do we allow signatures pagination

[anero]

I wonder if we should remove the old mechanism from the docs entirely.

I kind of want to retire the old pagination and other sources of perf pathology like this so we can save thousands of dollars by shrinking the database.

I also wonder what other API endpoints have the same pagination performance footgun. Do we allow signatures pagination

Makes sense, I'll remove the deprecated option from the docs.

re other places where we return paginated results: here are all the places where we use the partial that renders the meta pagination block for the authenticated API, so all of these presumably are using will_paginate for the results:

app/views/api/v1/calendars/events/index.json.jbuilder:
  16  json.meta do
  17:   json.partial! 'shared/pagination', items: @events
  18  end

app/views/api/v1/event_types/index.json.jbuilder:
  7  json.meta do
  8:   json.partial! 'shared/pagination', items: @event_types
  9  end

app/views/api/v1/events/index.json.jbuilder:
  7  json.meta do
  8:   json.partial! 'shared/pagination', items: @events
  9  end

app/views/api/v1/events/attendees/index.json.jbuilder:
  12  json.meta do
  13:   json.partial! 'shared/pagination', items: @actions
  14  end

app/views/api/v1/labels/index.json.jbuilder:
  5  json.meta do
  6:   json.partial! 'shared/pagination', items: @labels
  7  end

app/views/api/v1/local_chapters/index.json.jbuilder:
  7  json.meta do
  8:   json.partial! 'shared/pagination', items: @local_chapters
  9  end

app/views/api/v1/local_chapters/members/index.json.jbuilder:
  15  json.meta do
  16:   json.partial! 'shared/pagination', items: @local_chapter_members
  17  end

app/views/api/v1/partnerships/index.json.jbuilder:
  7  json.meta do
  8:   json.partial! 'shared/pagination', items: @partnerships
  9  end

app/views/api/v1/partnerships/events/index.json.jbuilder:
  12  json.meta do
  13:   json.partial! 'shared/pagination', items: @events
  14  end

app/views/api/v1/partnerships/petitions/index.json.jbuilder:
  12  json.meta do
  13:   json.partial! 'shared/pagination', items: @petitions
  14  end

app/views/api/v1/petitions/index.json.jbuilder:
  11    else
  12:     json.partial! 'shared/pagination', items: @petitions
  13    end

app/views/api/v1/petitions/signatures/index.json.jbuilder:
  12  json.meta do
  13:   json.partial! 'shared/pagination', items: @actions
  14  end

app/views/api/v1/signatures/index.json.jbuilder:
  7  json.meta do
  8:   json.partial! 'shared/pagination', items: @signatures
  9  end

app/views/api/v1/unsubscribes/index.json.jbuilder:
  7  json.meta do
  8:   json.partial! 'shared/pagination', items: @unsubscribes
  9  end