Repository navigation
Spell out how API versioning works across the docs - #63
Merged
Merged
Conversation
A top-to-bottom review after moving the version into the Substratal-Version header: - NFR: what counts as a breaking change; Deprecation (RFC 9745) and Sunset (RFC 8594) go on responses to requests naming the deprecated version; after Sunset, that version is 400 unsupported_api_version - Conventions: the same retirement rule, and that a webhook subscription's payload api_version is a separate version - Webhooks -> Payload versions: independent of Substratal-Version - OpenAPI Specification: versions are numbers, not URL prefixes - Auth -> POST /auth/oauth/token: no version header needed, and why - Glossary: API version and Payload version - Changelog entry Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
tools.json embeds the Glossary as an MCP resource, so gen-check failed. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
terraform plan (production)This is exactly what merging will change in AWS. Plan |
Adron
added a commit
that referenced
this pull request
Oct 22, 2026
Brings in the Substratal-Version header and root paths (#37), the plan-job secret fix (#59), and the versioning docs (#63). - Conflicts: plan-remaining.md keeps this branch's removal of the now-built section; Auth -> Lifetime keeps this branch's wording with root paths and anchors; the Changelog puts this branch's entry above main's two 2026-10-21 entries - openapi.yaml 1.0.0-draft.5 (main took draft.4 for the header change) - test_user_expiry_test.go: root paths; tools.json regenerated Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adron
added a commit
that referenced
this pull request
Oct 22, 2026
Brings in the Substratal-Version header and root paths (#37), the plan-job secret fix (#59), and the versioning docs (#63). - Conflicts in Applications (API and domain model), NFR, and plan-remaining.md: this branch's text, with root paths and anchors; main's side only differed by the removed /v1 prefix. The Changelog puts this branch's entry above main's two 2026-10-21 entries - openapi.yaml 1.0.0-draft.5 (main took draft.4 for the header change) - applications_test.go, the self_registered description, and an Auth anchor: root paths; tools.json regenerated Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adron
added a commit
that referenced
this pull request
Oct 22, 2026
Brings in the Substratal-Version header and root paths (#37), the plan-job secret fix (#59), and the versioning docs (#63). - Conflicts in Audit, Orders & Audit, and NFR: this branch's rows, with root paths; main's side only differed by the removed /v1 prefix. The Changelog puts this branch's entry above main's two 2026-10-21 entries - openapi.yaml 1.0.0-draft.5 (main took draft.4 for the header change) - Root paths in audit_exports_test.go and in comments, descriptions, and docs this branch added; tools.json regenerated Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adron
added a commit
that referenced
this pull request
Oct 22, 2026
Brings in the Substratal-Version header and root paths (#37), the plan-job secret fix (#59), and the versioning docs (#63). - /scim/v2 is exempt from Substratal-Version: identity providers (Okta, Entra ID, Google Workspace) can't add custom headers, and SCIM versions itself in the path. Without this every IdP request would be 400 api_version_required. The scim-token endpoints still need it. Conventions, SCIM, openapi.yaml's description, and the Changelog say so - scimCall sends no Substratal-Version, the way an IdP does, so the whole SCIM suite exercises the exemption; testenv skips contract validation for /scim/ (it follows RFC 7644, not openapi.yaml) - Conflicts in Organizations and Orders & Audit: this branch's rows, with root paths; plan-remaining.md is main's (this branch didn't change it). The Changelog puts this branch's entry above main's two entries - openapi.yaml 1.0.0-draft.5 (main took draft.4 for the header change) - Root paths in scim.md, scim.go, and scim_test.go; tools.json regenerated Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 22, 2026
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
1 participant
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.
Summary
A top-to-bottom review of the docs after #37 moved the API version into the
Substratal-Versionheader. Most pages already described it correctly. This fixes the gaps:Deprecation(RFC 9745, not RFC 8594 as the docs said) andSunset(RFC 8594) go on responses to requests that name the deprecated version. After theSunsetdate, requests naming it get400 unsupported_api_version. This is now stated in Conventions and NFR.Substratal-Versionrequest header and a webhook subscription's payloadapi_versiondate are independent. This is now said on Conventions and Webhooks, and both have Glossary entries.POST /auth/oauth/tokennotes in the section itself that it doesn't need the header, and why.Docs only: no API behavior changes. A local site build checked 2,415 in-site links and found no broken anchors.
🤖 Generated with Claude Code