ref(api): use token operationIds + summary for replay endpoints by betegon · Pull Request #117166 · getsentry/sentry

betegon · 2026-06-09T11:40:54Z

Summary

OpenAPI operationId is meant to be a machine identifier, but Sentry uses the human sentence (e.g. Retrieve a Count of Replays for a Given Issue or Transaction). That sentence is what the generated @sentry/api SDK turns into function names, and what the API reference renders as the page title and URL slug.

This moves the sentence into summary (the human title) and sets operation_id to a short camelCase token for the replay endpoints. The SDK then gets clean names (getOrganizationReplayCount, listOrganizationReplays, getOrganizationReplay, …), and — paired with getsentry/sentry-docs#18322, which makes the reference derive its title/slug from summary — the docs title and SEO-critical URLs stay byte-identical.

This is the pilot area of a broader operationId→token migration (batched per CODEOWNERS area). A couple of replay GETs that were mislabeled list are corrected here too (e.g. the replay count is a get, not a list).

Changes

10 replay endpoint files: operation_id → camelCase token, summary = the original sentence.

Test plan

make build-api-docs (drf-spectacular) regenerates and passes --validate --fail-on-warn; the regenerated spec shows the replay operations with token operationIds, the sentence preserved as summary, and description intact.
prek (ruff/flake8/mypy + the @extend_schema response-type check) passes on all changed files.

Depends on getsentry/sentry-docs #18322 landing first so docs titles/slugs are unaffected.

OpenAPI operationId is meant to be a machine identifier, but Sentry uses the human sentence ("Retrieve a Count of Replays..."). That sentence is what the SDK generator turns into function names and what the docs render as the title and URL slug. Move the sentence into `summary` (the human title) and set `operation_id` to a short camelCase token. The generated SDK gets clean names (`getOrganizationReplayCount`, `listOrganizationReplays`, ...) and, paired with getsentry/sentry-docs #18322, the docs title and SEO-critical URL slug stay byte-identical (both now derive from `summary`). First area of the operationId->token migration; replays chosen as the pilot.

The /replays/jobs/delete/ path produced awkward structural names (createProjectReplaysJobsDelete reads like a delete). Use the endpoint's own domain term (ReplayDeletionJobListResponse) for clearer tokens: list/create/getProjectReplayDeletionJob(s). Summaries unchanged.

betegon · 2026-06-10T12:50:14Z

Part of the operationId→token migration — sibling area PRs:

Dashboards (next area): ref(api): use token operationIds + summary for dashboard endpoints #117297
Convention doc (src/AGENTS.md): docs(api): document operation_id naming convention #117285
Docs SEO foundation: getsentry/sentry-docsfeat(mail): Add stats to MailPlugin and MailAdapter so that we can monitor the migration. #18322 (merged)

…117297) ## Summary Second area of the operationId→token migration. OpenAPI `operationId` is meant to be a machine identifier, but Sentry uses the human sentence — which the generated `@sentry/api` SDK turns into function names and the API reference renders as the page title + URL slug. This moves the sentence into `summary` and sets `operation_id` to a short camelCase REST token for the **dashboard** endpoints. The SDK gets clean names; paired with the merged docs change (title/slug derive from `summary`), the docs titles and SEO URLs stay byte-identical. 5 operations, 2 files, all textbook CRUD (no exceptions): `listOrganizationDashboards` · `createOrganizationDashboard` · `getOrganizationDashboard` · `updateOrganizationDashboard` · `deleteOrganizationDashboard` ## Test plan - `make build-api-docs` regenerates the spec and passes `--validate --fail-on-warn`; dashboard ops show token operationIds with the sentence preserved as `summary`. - prek green (ruff/flake8/mypy + the `@extend_schema` response-type check). ## Related (operationId→token migration) - Convention documented in `src/AGENTS.md`: #117285 - Replays pilot (first area): #117166 - Docs SEO foundation (title/slug from summary): getsentry/sentry-docs #18322 (merged)

…17302) ## Summary Third area of the operationId→token migration. Move the human sentence into `summary` and set `operation_id` to a short camelCase REST token, so the generated `@sentry/api` SDK gets clean names while docs titles/slugs stay byte-identical (derived from `summary`). 5 operations, 2 files. The path is `/discover/saved/`, so the pure structural token drops the resource noun (`…DiscoverSaved`). Overridden to the endpoint's own term — `DiscoverSavedQuery` (per `DiscoverSavedQuerySerializer`) — for clarity: - `listOrganizationDiscoverSavedQueries` - `createOrganizationDiscoverSavedQuery` - `getOrganizationDiscoverSavedQuery` - `updateOrganizationDiscoverSavedQuery` - `deleteOrganizationDiscoverSavedQuery` ## Test plan - `make build-api-docs` regenerates the spec and passes `--validate --fail-on-warn`; operations show token operationIds with the sentence preserved as `summary`. - prek green (ruff/flake8/mypy + the `@extend_schema` response-type check). ## Related (operationId→token migration) - Convention doc (`src/AGENTS.md`): #117285 - Replays pilot: #117166 · Dashboards: #117297 - Docs SEO foundation: getsentry/sentry-docs #18322 (merged)

…117297) ## Summary Second area of the operationId→token migration. OpenAPI `operationId` is meant to be a machine identifier, but Sentry uses the human sentence — which the generated `@sentry/api` SDK turns into function names and the API reference renders as the page title + URL slug. This moves the sentence into `summary` and sets `operation_id` to a short camelCase REST token for the **dashboard** endpoints. The SDK gets clean names; paired with the merged docs change (title/slug derive from `summary`), the docs titles and SEO URLs stay byte-identical. 5 operations, 2 files, all textbook CRUD (no exceptions): `listOrganizationDashboards` · `createOrganizationDashboard` · `getOrganizationDashboard` · `updateOrganizationDashboard` · `deleteOrganizationDashboard` ## Test plan - `make build-api-docs` regenerates the spec and passes `--validate --fail-on-warn`; dashboard ops show token operationIds with the sentence preserved as `summary`. - prek green (ruff/flake8/mypy + the `@extend_schema` response-type check). ## Related (operationId→token migration) - Convention documented in `src/AGENTS.md`: #117285 - Replays pilot (first area): #117166 - Docs SEO foundation (title/slug from summary): getsentry/sentry-docs #18322 (merged)

…17302) ## Summary Third area of the operationId→token migration. Move the human sentence into `summary` and set `operation_id` to a short camelCase REST token, so the generated `@sentry/api` SDK gets clean names while docs titles/slugs stay byte-identical (derived from `summary`). 5 operations, 2 files. The path is `/discover/saved/`, so the pure structural token drops the resource noun (`…DiscoverSaved`). Overridden to the endpoint's own term — `DiscoverSavedQuery` (per `DiscoverSavedQuerySerializer`) — for clarity: - `listOrganizationDiscoverSavedQueries` - `createOrganizationDiscoverSavedQuery` - `getOrganizationDiscoverSavedQuery` - `updateOrganizationDiscoverSavedQuery` - `deleteOrganizationDiscoverSavedQuery` ## Test plan - `make build-api-docs` regenerates the spec and passes `--validate --fail-on-warn`; operations show token operationIds with the sentence preserved as `summary`. - prek green (ruff/flake8/mypy + the `@extend_schema` response-type check). ## Related (operationId→token migration) - Convention doc (`src/AGENTS.md`): #117285 - Replays pilot: #117166 · Dashboards: #117297 - Docs SEO foundation: getsentry/sentry-docs #18322 (merged)

) ## Summary OpenAPI `operationId` is meant to be a machine identifier, but Sentry uses the human sentence (e.g. `Retrieve a Count of Replays for a Given Issue or Transaction`). That sentence is what the generated `@sentry/api` SDK turns into function names, and what the API reference renders as the page title **and** URL slug. This moves the sentence into `summary` (the human title) and sets `operation_id` to a short camelCase token for the **replay** endpoints. The SDK then gets clean names (`getOrganizationReplayCount`, `listOrganizationReplays`, `getOrganizationReplay`, …), and — paired with [getsentry/sentry-docs #18322](getsentry/sentry-docs#18322), which makes the reference derive its title/slug from `summary` — the docs title and SEO-critical URLs stay **byte-identical**. This is the **pilot area** of a broader operationId→token migration (batched per CODEOWNERS area). A couple of replay GETs that were mislabeled `list` are corrected here too (e.g. the replay *count* is a `get`, not a `list`). ## Changes - 10 replay endpoint files: `operation_id` → camelCase token, `summary` = the original sentence. ## Test plan - `make build-api-docs` (drf-spectacular) regenerates and passes `--validate --fail-on-warn`; the regenerated spec shows the replay operations with token operationIds, the sentence preserved as `summary`, and `description` intact. - prek (ruff/flake8/mypy + the `@extend_schema` response-type check) passes on all changed files. Depends on getsentry/sentry-docs #18322 landing first so docs titles/slugs are unaffected.

…117337) ## Summary operationId→token migration, **batch 1 of 3** (core + api endpoints, **83 ops / 50 files**). Moves the human sentence into `summary` and sets `operation_id` to a short camelCase REST token so the generated `@sentry/api` SDK gets clean names; docs titles/slugs stay byte-identical (derived from `summary`). Most are straight CRUD (`getOrganization`, `listProjectKeys`, `updateProject`, …). Verb-corrected and ad-hoc overrides where the path couldn't express intent: - non-CRUD verbs: `addProjectTeam`, `addOrganizationMember`, `linkProjectRepository`, `registerProjectServiceHook`, `provisionOrganizationScimV2User`/`Group` - singleton GETs → `get`: `getOrganizationProfilingFlamegraph`, `getOrganizationSessions`, `getOrganizationStatsSummary`, `getProjectEventSourceMapDebug` - consistency/clarity: symbol-source detail ops singular (`delete`/`updateProjectSymbolSource`), `listOrganizationTraceItemAttributes`, `listProjectDebugFiles` ## Test plan - prek green (ruff/flake8/mypy + `@extend_schema` response-type check). - CI `api docs test` regenerates + validates the spec (`--fail-on-warn`); operations show token operationIds with the sentence preserved as `summary`. ## Related (operationId→token migration) - Convention: #117285 · Merged: replays #117166, dashboards #117297, discover #117302 - Docs SEO foundation: getsentry/sentry-docs #18322 (merged) - Batches 2 & 3 to follow (issues/integrations/releases/workflow_engine; preprod/monitors/sentry_apps/notifications/seer/feedback) ⚠️ Merge note: the schema publish job has no concurrency guard — **don't merge the 3 batches simultaneously** (caused a partial-release race last time). Space them out.

…leases/workflow endpoints (#117339) ## Summary operationId→token migration, **batch 2 of 3** (issues, integrations, releases, workflow_engine — **62 ops / 38 files**). Sentence → `summary`, `operation_id` → short camelCase REST token; docs titles/slugs unchanged (derived from `summary`). Overrides where the path/verb didn't capture intent: - `resolveOrganizationEventId` / `resolveOrganizationShortId` (resolve verb + `Id` casing) - `upload{Organization,Project}ReleaseFile`, `getOrganizationConfigIntegrations` - `getProjectOwnership` kept consistent with `updateProjectOwnership` Bulk operations correctly keep the plural form (`deleteOrganizationIssues`, `updateOrganizationDetectors`, `updateOrganizationWorkflows`) vs their singular detail counterparts. ## Test plan - prek green; CI `api docs test` regenerates + validates the spec (`--fail-on-warn`). ## Related - Batch 1 (core+api): #117337 · Convention: #117285 · Merged: #117166 #117297 #117302 - Batch 3 (preprod/monitors/sentry_apps/notifications/seer/feedback) to follow. ⚠️ Don't merge the batches simultaneously — the schema publish job has no concurrency guard (caused a partial-release race before). Space them out.

…y_apps/notifications/seer/feedback endpoints (#117403) ## Summary operationId→token migration, **batch 3 of 3** (preprod, monitors, sentry_apps, notifications, seer, feedback — **35 ops / 22 files**). Sentence → `summary`, `operation_id` → short camelCase REST token; docs titles/slugs unchanged (derived from `summary`). Overrides: - `startOrganizationIssueAutofix` / `getOrganizationIssueAutofixState` (seer) - unified all preprod ops to `PreprodArtifact` casing (structural produced inconsistent `Preprodartifacts`), and fixed the latest-base singleton to `getOrganizationPreprodArtifactSnapshotLatestBase` (was a mislabeled `list`) monitors map to the `Detector`/`Monitor` paths as-is; notifications-action ops are self-consistent. ## Test plan - prek green; CI `api docs test` regenerates + validates the spec (`--fail-on-warn`). ## Related - Batch 1 (core+api): #117337 · Batch 2 (issues/integrations/releases/workflow): #117339 - Convention: #117285 · Merged: #117166 #117297 #117302 ⚠️ Don't merge the batches simultaneously — the schema publish job has no concurrency guard (caused a partial-release race before). Space them out (merge one, wait for its `openapi` publish, then the next).

…117337) ## Summary operationId→token migration, **batch 1 of 3** (core + api endpoints, **83 ops / 50 files**). Moves the human sentence into `summary` and sets `operation_id` to a short camelCase REST token so the generated `@sentry/api` SDK gets clean names; docs titles/slugs stay byte-identical (derived from `summary`). Most are straight CRUD (`getOrganization`, `listProjectKeys`, `updateProject`, …). Verb-corrected and ad-hoc overrides where the path couldn't express intent: - non-CRUD verbs: `addProjectTeam`, `addOrganizationMember`, `linkProjectRepository`, `registerProjectServiceHook`, `provisionOrganizationScimV2User`/`Group` - singleton GETs → `get`: `getOrganizationProfilingFlamegraph`, `getOrganizationSessions`, `getOrganizationStatsSummary`, `getProjectEventSourceMapDebug` - consistency/clarity: symbol-source detail ops singular (`delete`/`updateProjectSymbolSource`), `listOrganizationTraceItemAttributes`, `listProjectDebugFiles` ## Test plan - prek green (ruff/flake8/mypy + `@extend_schema` response-type check). - CI `api docs test` regenerates + validates the spec (`--fail-on-warn`); operations show token operationIds with the sentence preserved as `summary`. ## Related (operationId→token migration) - Convention: #117285 · Merged: replays #117166, dashboards #117297, discover #117302 - Docs SEO foundation: getsentry/sentry-docs #18322 (merged) - Batches 2 & 3 to follow (issues/integrations/releases/workflow_engine; preprod/monitors/sentry_apps/notifications/seer/feedback) ⚠️ Merge note: the schema publish job has no concurrency guard — **don't merge the 3 batches simultaneously** (caused a partial-release race last time). Space them out.

…leases/workflow endpoints (#117339) ## Summary operationId→token migration, **batch 2 of 3** (issues, integrations, releases, workflow_engine — **62 ops / 38 files**). Sentence → `summary`, `operation_id` → short camelCase REST token; docs titles/slugs unchanged (derived from `summary`). Overrides where the path/verb didn't capture intent: - `resolveOrganizationEventId` / `resolveOrganizationShortId` (resolve verb + `Id` casing) - `upload{Organization,Project}ReleaseFile`, `getOrganizationConfigIntegrations` - `getProjectOwnership` kept consistent with `updateProjectOwnership` Bulk operations correctly keep the plural form (`deleteOrganizationIssues`, `updateOrganizationDetectors`, `updateOrganizationWorkflows`) vs their singular detail counterparts. ## Test plan - prek green; CI `api docs test` regenerates + validates the spec (`--fail-on-warn`). ## Related - Batch 1 (core+api): #117337 · Convention: #117285 · Merged: #117166 #117297 #117302 - Batch 3 (preprod/monitors/sentry_apps/notifications/seer/feedback) to follow. ⚠️ Don't merge the batches simultaneously — the schema publish job has no concurrency guard (caused a partial-release race before). Space them out.

…y_apps/notifications/seer/feedback endpoints (#117403) ## Summary operationId→token migration, **batch 3 of 3** (preprod, monitors, sentry_apps, notifications, seer, feedback — **35 ops / 22 files**). Sentence → `summary`, `operation_id` → short camelCase REST token; docs titles/slugs unchanged (derived from `summary`). Overrides: - `startOrganizationIssueAutofix` / `getOrganizationIssueAutofixState` (seer) - unified all preprod ops to `PreprodArtifact` casing (structural produced inconsistent `Preprodartifacts`), and fixed the latest-base singleton to `getOrganizationPreprodArtifactSnapshotLatestBase` (was a mislabeled `list`) monitors map to the `Detector`/`Monitor` paths as-is; notifications-action ops are self-consistent. ## Test plan - prek green; CI `api docs test` regenerates + validates the spec (`--fail-on-warn`). ## Related - Batch 1 (core+api): #117337 · Batch 2 (issues/integrations/releases/workflow): #117339 - Convention: #117285 · Merged: #117166 #117297 #117302 ⚠️ Don't merge the batches simultaneously — the schema publish job has no concurrency guard (caused a partial-release race before). Space them out (merge one, wait for its `openapi` publish, then the next).

github-actions Bot added the Scope: Backend Automatically applied to PRs that change backend components label Jun 9, 2026

betegon marked this pull request as ready for review June 10, 2026 09:45

Merge branch 'master' into api/operation-id-tokens-replays

37e5405

betegon requested a review from a team as a code owner June 10, 2026 09:45

vercel Bot deployed to Preview June 10, 2026 09:47 View deployment

This was referenced Jun 10, 2026

docs(api): document operation_id naming convention #117285

Closed

ref(api): use token operationIds + summary for dashboard endpoints #117297

Merged

betegon mentioned this pull request Jun 10, 2026

ref(api): use token operationIds + summary for discover endpoints #117302

Merged

gricha approved these changes Jun 10, 2026

View reviewed changes

betegon merged commit c571301 into master Jun 10, 2026
64 of 65 checks passed

betegon deleted the api/operation-id-tokens-replays branch June 10, 2026 17:03

This was referenced Jun 10, 2026

ref(api): use token operationIds + summary for core + api endpoints #117337

Merged

ref(api): use token operationIds + summary for issues/integrations/releases/workflow endpoints #117339

Merged

betegon mentioned this pull request Jun 11, 2026

ref(api): use token operationIds + summary for preprod/monitors/sentry_apps/notifications/seer/feedback endpoints #117403

Merged

sentry-release-bot Bot mentioned this pull request Jun 15, 2026

publish: getsentry/sentry@26.6.0 getsentry/publish#8571

Closed

3 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

ref(api): use token operationIds + summary for replay endpoints#117166

ref(api): use token operationIds + summary for replay endpoints#117166
betegon merged 3 commits into
masterfrom
api/operation-id-tokens-replays

betegon commented Jun 9, 2026 •

edited

Loading

Uh oh!

betegon commented Jun 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

betegon commented Jun 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Test plan

Uh oh!

betegon commented Jun 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

betegon commented Jun 9, 2026 •

edited

Loading