Skip to content

poc(api): add date-based per-operation API versioning#38300

Draft
nogates wants to merge 2 commits into
masterfrom
walid/versioning-poc-operations
Draft

poc(api): add date-based per-operation API versioning#38300
nogates wants to merge 2 commits into
masterfrom
walid/versioning-poc-operations

Conversation

@nogates

@nogates nogates commented Jul 20, 2026

Copy link
Copy Markdown
Contributor

Summary

Draft POC for date-based per-operation API versioning. Split from #38028, which now contains only the API changelog page.

  • Operations flagged x-datadog-api-versioned render a per-operation version selector with available dates, lifecycle tags, and a Follow global action.
  • A Global API version control in the sidebar sets the baseline date for versioned operations unless an operation has an override.
  • Request and response schema panes render one variant per version with New in and Removed in change markers.
  • Large oneOf pruning is scoped to date-versioned schemas so generated examples remain below the GitHub file-size limit without affecting unrelated schemas.

This is a design POC for reviewer walkthrough, not intended to merge as-is.

Test plan

  • Visit /api/latest/dashboards/create-a-new-dashboard/ and confirm the per-operation version selector lists 2026-04-01, 2026-06-01, and 2026-07-01 with the correct lifecycle tags.
  • Confirm the sidebar Global API version selector changes the baseline version for operations following it.
  • Confirm per-operation overrides persist independently and Follow global clears an override.
  • Confirm New in and Removed in markers render on the version pane where each schema change was introduced.
  • Confirm the sidebar version selector aligns with the search box and navigation tree.

@nogates
nogates force-pushed the walid/versioning-poc-operations branch from d964b9b to 15e331d Compare July 20, 2026 12:29
@github-actions github-actions Bot added the Architecture Everything related to the Doc backend label Jul 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Architecture Everything related to the Doc backend

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant