Skip to content

fix(api): Add missing cursor query parameter to paginated endpoint OpenAPI schemas#109642

Merged
MathurAditya724 merged 2 commits intomasterfrom
fix/adi/openapi-docs
Mar 2, 2026
Merged

fix(api): Add missing cursor query parameter to paginated endpoint OpenAPI schemas#109642
MathurAditya724 merged 2 commits intomasterfrom
fix/adi/openapi-docs

Conversation

@MathurAditya724
Copy link
Member

Summary

  • Adds CursorQueryParam to @extend_schema parameters on 19 paginated API endpoints that support cursor-based pagination at runtime (self.paginate()) but were missing the cursor query parameter in their OpenAPI spec
  • This is a schema-only change — no runtime behavior is modified. The cursor parameter already works at runtime because self.paginate() reads it from request.GET; this just makes the OpenAPI spec accurately reflect that

Motivation

The getsentry/sentry-api-schema repo (which produces the @sentry/api npm package) consumes the OpenAPI spec generated from this repo. The missing cursor declarations cause the generated TypeScript SDK to produce types where query is never or omits cursor, making type-safe pagination impossible for SDK consumers.

Upstream issues:

Endpoints Modified

Priority 1 — High-impact (actively blocking SDK consumers)

Endpoint File
GET /organizations/{org}/repos/ src/sentry/integrations/api/endpoints/organization_repositories.py
GET /organizations/{org}/releases/ src/sentry/api/endpoints/organization_releases.py
GET /organizations/{org}/members/ src/sentry/core/endpoints/organization_member_index.py
GET /organizations/{org}/issues/{issue_id}/events/ src/sentry/issues/endpoints/group_events.py

Priority 2 — Other paginated endpoints

Endpoint File
GET /organizations/{org}/integrations/ organization_integrations_index.py
GET /organizations/{org}/monitors/ organization_monitor_index.py
GET /organizations/{org}/monitors/{monitor}/checkins/ organization_monitor_checkin_index.py
GET /organizations/{org}/releases/{version}/commits/ organization_release_commits.py
GET /organizations/{org}/releases/{version}/deploys/ release_deploys.py
GET /organizations/{org}/releases/{version}/files/ organization_release_files.py
GET /organizations/{org}/repos/{repo_id}/commits/ organization_repository_commits.py
GET /organizations/{org}/sentry-app-installations/ sentry_app_installations.py
GET /projects/{org}/{project}/releases/{version}/commits/ project_release_commits.py
GET /projects/{org}/{project}/releases/{version}/files/ project_release_files.py
GET /projects/{org}/{project}/rules/ project_rules.py
GET /projects/{org}/{project}/tags/{key}/values/ project_tagkey_values.py
GET /projects/{org}/{project}/teams/ project_teams.py
GET /projects/{org}/{project}/user-feedback/ project_user_reports.py
GET /projects/{org}/{project}/users/ project_users.py

Endpoints from plan intentionally skipped (do NOT paginate)

These were listed in the plan but return full results directly without self.paginate():

  • OrganizationUserTeamsEndpoint — returns Response(serialize(list(queryset), ...))
  • ProjectEnvironmentsEndpoint — returns Response(serialize(list(queryset), ...))
  • ProjectMemberIndexEndpoint — returns Response(context) with manual sort

How It Works

The CursorQueryParam serializer is defined in src/sentry/apidocs/parameters.py and declares a single optional cursor string field. Adding it to @extend_schema(parameters=[...]) causes drf-spectacular to include the cursor query parameter in the generated OpenAPI JSON for that endpoint.

Fixes getsentry/sentry-api-schema#59
Fixes getsentry/sentry-api-schema#60

@github-actions github-actions bot added the Scope: Backend Automatically applied to PRs that change backend components label Mar 2, 2026
…enAPI schemas

Add CursorQueryParam to @extend_schema parameters on 19 paginated API
endpoints that support cursor-based pagination at runtime but were missing
the cursor parameter in their OpenAPI spec. This is a schema-only change
with no runtime behavior modification.

Fixes getsentry/sentry-api-schema#59
Fixes getsentry/sentry-api-schema#60
@MathurAditya724 MathurAditya724 marked this pull request as ready for review March 2, 2026 07:58
@MathurAditya724 MathurAditya724 requested review from a team as code owners March 2, 2026 07:58
Copy link
Member

@JoshFerge JoshFerge left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

for some of these endpoints, the api docs may not be based on the in-code tooling, for example the user reports

"description": "Return a list of user feedback items within this project.\n\n*This list does not include submissions from the [User Feedback Widget](https://docs.sentry.io/product/user-feedback/#user-feedback-widget). This is because it is based on an older format called User Reports - read more [here](https://develop.sentry.dev/application/feedback-architecture/#user-reports). To return a list of user feedback items from the widget, please use the [issue API](https://docs.sentry.io/api/events/list-a-projects-issues/) with the filter `issue.category:feedback`.*",

will need the json there updated

…N API docs

11 endpoints have hand-maintained OpenAPI JSON files in api-docs/paths/
that also need the cursor query parameter. Added PaginationCursor $ref
to each file's get.parameters array, matching the existing convention
used by service-hooks, project-issues, and issue-hashes.
@MathurAditya724 MathurAditya724 requested a review from a team as a code owner March 2, 2026 08:22
@MathurAditya724 MathurAditya724 merged commit 54e3dd8 into master Mar 2, 2026
74 of 75 checks passed
@MathurAditya724 MathurAditya724 deleted the fix/adi/openapi-docs branch March 2, 2026 09:02
jan-auer added a commit that referenced this pull request Mar 2, 2026
…ept-encoding

* origin/master: (63 commits)
  fix(api): Add missing cursor query parameter to paginated endpoint OpenAPI schemas (#109642)
  docs(sentry-apps): Add sentryAppId to sentry-app-installations API schema (#109628)
  feat(occurrences on eap): Implement double reads from EAP in organization events trace API endpoint (#109391)
  feat(occurrences on eap): Implement double reads from EAP for reprocessing2 flow (#109345)
  feat(ci): report backend test fails (#109543)
  feat(seer): Add signed viewer context header to Seer API requests (#109626)
  devenv: cleanup devenv-managed uv (#109617)
  feat(seer): Iterate on the instructions at the top of seer settings pages (#109586)
  ref(seer): Add typed wrappers for remaining Seer API callsites (#109607)
  feat(preprod): Make snapshots endpoint org scoped (#109575)
  chore: capture exception (#109620)
  fix(formatting): run ruff format (#109618)
  feat(preprod): Create admin gated recompare snapshots endpoint (#109546)
  feat(cells): expand locality/cell distinction (#109538)
  feat(cells): add db migration for synapse (#109615)
  feat(preprod): Add public install-details endpoint and shared utilities (#109583)
  fix(tests): Fix flaky test_cross_trace_query_with_spans_and_logs (#109572)
  fix(grouping): Resolve mypy possibly-undefined errors in grouphash caching (#109602)
  fix(dashboards): Default axisRange to auto for existing widgets in builder (#109598)
  fix(billing): Fix category display names in pending changes (#109612)
  ...
BYK added a commit to getsentry/cli that referenced this pull request Mar 2, 2026
…ounds

The @sentry/api SDK now has cursor support for all paginated endpoints
(sentry-api-schema#59, #60 fixed via getsentry/sentry#109642).

Migrated 5 functions from raw HTTP (orgScopedRequestPaginated) to SDK:
- listProjects: SDK auto-pagination loop
- listProjectsPaginated: SDK + unwrapPaginatedResult
- listRepositories: SDK + unwrapResult (was apiRequestToRegion)
- listRepositoriesPaginated: SDK + unwrapPaginatedResult
- listTeamsPaginated: SDK + unwrapPaginatedResult

Removed dead infrastructure:
- extractOrgSlugFromEndpoint + regex constants
- orgScopedRequestPaginated
- orgScopedPaginateAll

All list functions now consistently use the SDK with our custom
unwrapResult/unwrapPaginatedResult for proper error type preservation.
BYK added a commit to getsentry/cli that referenced this pull request Mar 3, 2026
…ounds

The @sentry/api SDK now has cursor support for all paginated endpoints
(sentry-api-schema#59, #60 fixed via getsentry/sentry#109642).

Migrated 5 functions from raw HTTP (orgScopedRequestPaginated) to SDK:
- listProjects: SDK auto-pagination loop
- listProjectsPaginated: SDK + unwrapPaginatedResult
- listRepositories: SDK + unwrapResult (was apiRequestToRegion)
- listRepositoriesPaginated: SDK + unwrapPaginatedResult
- listTeamsPaginated: SDK + unwrapPaginatedResult

Removed dead infrastructure:
- extractOrgSlugFromEndpoint + regex constants
- orgScopedRequestPaginated
- orgScopedPaginateAll

All list functions now consistently use the SDK with our custom
unwrapResult/unwrapPaginatedResult for proper error type preservation.
BYK added a commit to getsentry/cli that referenced this pull request Mar 3, 2026
…orkarounds (#321)

## Summary

Upgrades `@sentry/api` from `^0.1.0` to `^0.21.0` and removes the
raw-HTTP pagination workarounds we had in place for
[sentry-api-schema#59](getsentry/sentry-api-schema#59)
and
[sentry-api-schema#60](getsentry/sentry-api-schema#60),
both fixed by
[getsentry/sentry#109642](getsentry/sentry#109642).

## What changed

**5 functions** migrated from raw HTTP to SDK calls:

| Function | Before | After |
|---|---|---|
| `listProjects` | `orgScopedPaginateAll` (raw HTTP loop) | SDK loop via
`listAnOrganization_sProjects` |
| `listProjectsPaginated` | `orgScopedRequestPaginated` | SDK +
`unwrapPaginatedResult` |
| `listRepositories` | `apiRequestToRegion` | SDK + `unwrapResult` via
`listAnOrganization_sRepositories` |
| `listRepositoriesPaginated` | `orgScopedRequestPaginated` | SDK +
`unwrapPaginatedResult` |
| `listTeamsPaginated` | `orgScopedRequestPaginated` | SDK +
`unwrapPaginatedResult` |

**~105 lines of dead infrastructure removed:**
- `extractOrgSlugFromEndpoint` + regex constants
- `orgScopedRequestPaginated`
- `orgScopedPaginateAll`

All list functions now follow the same consistent pattern: SDK call →
`unwrapResult` / `unwrapPaginatedResult`.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Scope: Backend Automatically applied to PRs that change backend components

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants