[sentry-junior]

Depends on: getsentry/sentry-api-schema#148 and getsentry/sentry-docs#20787. Merge both first. openapi.yml syncs this spec to sentry-api-schema on push to master. That repo then auto-releases @sentry/api and cascades into sentry-docs, and both still assume /api/0 in every path until those PRs land.

The public OpenAPI spec's server URL was the bare origin, and every path spelled out /api/0. Clients had to know the prefix, and the API version in it, instead of reading it from the spec. Now the server URL carries the versioned base path and paths are relative to it.

Before:

"servers": [{ "url": "https://{region}.sentry.io", "variables": { "region": { ... } } }],
"paths": { "/api/0/organizations/{organization_id_or_slug}/releases/": { ... } }

After:

"servers": [{ "url": "https://{region}.sentry.io/api/0", "variables": { "region": { ... } } }],
"paths": { "/organizations/{organization_id_or_slug}/releases/": { ... } }

How:

• SPECTACULAR_SETTINGS["SERVERS"] sets the URL to https://{region}.sentry.io/api/0.
• A new last postprocessing hook, relative_paths_hook, strips that base path from every path, so the hooks before it still see full paths. A path outside the base path fails the build.
• The hook also appends the base path to per-endpoint servers (only /seer/models/ today: https://{region}.sentry.io/api/0). Endpoint classes keep naming origins.
• I didn't use drf-spectacular's SCHEMA_PATH_PREFIX_TRIM: it doesn't trim the APPEND_PATHS we use, and custom_postprocessing_hook matches on full paths.

Versioning: the spec names /api/0 once. A future v1 is a new server entry or spec with /api/1, and downstream clients read the path from servers[0].url. I picked this over an /api/{version} server variable because a v1 overhaul would come with different paths and schemas, which one spec can't describe. Self-hosted stays as before: clients swap the origin and keep the path.

Breaking change for anyone reading the spec: paths no longer start with /api/0, so join them to the server URL. Known consumers:

• @sentry/api: handled by sentry-api-schemaAdded support for top level exception handling #148, which ships as 2.0.0. It reads both shapes and generates byte-identical clients from this spec and the master spec.
• docs.sentry.io API reference: handled by sentry-docsfeat(workflow): Using decorator for rate limiting this endpoint #20787. It renders the same page data from both shapes.
• getsentry/toolkit consumes @sentry/api and follows after the 2.0.0 release.

Nothing else in this repo reads the spec, apart from the openapi.yml sync and the openapi-diff comment workflow. The private investigation schema reuses these settings and now has the same shape; nothing consumes it.

Checks (run locally):

• make build-api-docs and make build-investigation-api-docs both pass. Against master, the derefed spec differs only in servers, the path keys and the seer op server.
• pnpm run validate-api-examples passes.
• pytest tests/apidocs passes (167). Tests changed:
  • RelativePathsHookTest is new.
  • APIDocsTestCase keeps the server URL path when it swaps the origin. Without that, openapi-core can't match any request (ServerNotFound).
  • Two endpoint tests read schema entries by path and now use relative keys.
• prek and mypy pass on the changed files.

via @BYK.

--

View Session [Sentry]

[BYK]

Wondering if we can somehow sync the spectacular settings with the api's mounted django route to prevent any future issues?

[sentry-junior]

Wondering if we can somehow sync the spectacular settings with the api's mounted django route to prevent any future issues?

Yes, done in 37d5255. There's now one constant, API_BASE_PATH = "/api/0" in sentry/conf/api_base_path.py, and both sides read it:

• sentry/web/urls.py mounts sentry.api.urls at path(f"{API_BASE_PATH.removeprefix('/')}/", include(...)), replacing re_path(r"^api/0/", ...).
• SPECTACULAR_SETTINGS["SERVERS"] builds its URL as https://{region}.sentry.io{API_BASE_PATH}.

The constant lives in sentry.conf because conf/server.py can't import sentry.api, which pulls in the API client. If the two ever drift anyway, relative_paths_hook already fails the build when a path isn't under the server URL's path.

Checks:

• make build-api-docs gives a byte-identical openapi-derefed.json.
• /api/0/organizations/ and /api/0/ still resolve to the same views.
• tests/apidocs and the API index tests pass, and so do prek and mypy.

getsentry mounts its own ^api/0/_admin/... routes separately. Those aren't in the public spec, so I left them alone; they could use the same constant in a follow-up.