feat(api): Badge experimental endpoints on API reference pages - #19320
Merged
DominikB2014 merged 2 commits intoSep 11, 2026
Conversation
Sentry marks endpoints published under the PUBLIC_EXPERIMENTAL status with x-sentry-experimental on the operation, but nothing read it, so those endpoints rendered as though they were stable. Model the extension, carry it onto the API type next to the existing deprecated flag, and render a badge above the request block.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
the
Priority: Needs Triage
Sentry prepends a text notice to every experimental operation's description so consumers without a badge still warn the reader. Rendering both said the same sentence twice on the page. Strip the notice when we render the badge, which also makes the two changes safe to merge in either order.
DominikB2014
marked this pull request as ready for review
September 11, 2026 14:30
Contributor
|
Please update the IS YOUR CHANGE URGENT? section of the PR description:
This information helps the Docs team prioritize your review. |
![sentry[bot]](https://avatars.githubusercontent.com/in/12637?s=60&v=4){kind=small}
Contributor
|
For ones that are already marked experimental, like this one? - should we switch it over to this new format? |
Contributor
Author
skaasten
approved these changes
Sep 11, 2026
DominikB2014
deleted the
dominikbuszowiecki/feat/api-experimental-badge
branch
September 11, 2026 16:24
DominikB2014
added a commit
to getsentry/sentry
that referenced
this pull request
Sep 11, 2026
This Pr makes two changes: 1. Adds `PUBLIC_EXPERIMENTAL` to `ApiPublishStatus`, filling the gap between an endpoint being invisible and being frozen under a permanent stability commitment — it is published, but free to change incompatibly. Plan is to make most of our private apis have this status, so code mode and external agents immediately benefit 2. Set the /trace-items/metrics endpoint to public experiemental (the first example) There is a complementary docs pr here getsentry/sentry-docs#19320, with a screenshot from me testing this all locally Publication is now expressed once as `ApiPublishStatus.is_published`, and every gate that keyed on `PUBLIC` reads it (the OpenAPI filter, the S022 response-shape lint, and the Seer public-API matrix), so the new status clears the exact same documentation bar as `PUBLIC` rather than offering a shortcut past it. Because nothing downstream renders the `x-sentry-experimental` marker these operations now carry, the build also prepends a short notice to the rendered description — four endpoints were already hand-writing that warning into their docstrings in four different wordings, one of them buried at the end, and this standardizes on the most common of them. The `trace-items/metrics` endpoint adopts the status as the first user: publishing it pulls it into the Seer matrix, which needs its feature flag registered there, and it gains a response example, with its response TypedDicts moving to a `*_types.py` so the examples module can import them without a circular import. Follow-ups: a sentry-docs badge reading `x-sentry-experimental` to replace the text notice, the Sentaur bot tolerating the new `public_experimental` key in the ownership stats JSON, and migrating those four hand-rolled endpoints onto the status.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds a experimental section if an endpoint is marked as public_experimental.
One thing to note, we have a regex that automatically strips the existing experimental message from the api description, this is intentional. We want that description in the openapi json so external tools (like postman, swagger ui, etc) understand it's experimental, but we want the docs to render a experimental badge so we have to strip out the existing description.