docs(api): TRA-791 BB68 — Authentication scope table + 401 detail strings + design-notes bodySerializer cross-link#184
Merged
Conversation
…ings + design-notes bodySerializer cross-link
F1: Add tag-subresource rows (POST/DELETE on assets/{id}/tags and
locations/{id}/tags) under the appropriate :write scopes, plus an
inheritance-rule bullet stating tag ops gate on the parent resource's
:write scope. Add a canonical-source note above the table pointing
readers at the x-required-scopes extension.
F2: Document all three 401 error.detail strings (missing header,
invalid/expired token, wrong scheme) in a new subsection under
Request header, with guidance to branch on error.type rather than
the diagnostic detail prose.
F3: Add a See-also pointer from the design-notes nullable section to
the openapi-fetch mergePatchMiddleware recipe in the quickstart, so
readers landing in design-notes for stack gotchas find the PATCH
Content-Type fix in one hop.
|
🚀 Preview Deployment Update ✅ This PR has been successfully merged into the preview branch. The preview environment will update shortly at: https://docs.preview.trakrf.id |
Deploying docs with
|
| Latest commit: |
ba4b808
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://3a664933.docs-4n7.pages.dev |
| Branch Preview URL: | https://preview.docs-4n7.pages.dev |
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
Docs-side of TRA-791 (BB68). Three customer-facing reference-page corrections; no runtime behavior changes; no changelog. Platform-side (F4) is closed per the audit comment — the spec already carries
x-required-scopeson every operation.POST/DELETEonassets/{id}/tagsandlocations/{id}/tags) under the appropriate:writescopes. Added an inheritance-rule bullet ("tag ops gate on the parent's:writescope — no separatetags:*scope"). Added a canonical-source note above the table pointing readers at thex-required-scopesextension as the authoritative mapping.error.detailstrings (missing header / invalid or expired token / wrong scheme) with guidance to branch onerror.typerather than the diagnostic prose.openapi-fetch?" pointer at the end of the nullable section in design-notes that links to themergePatchMiddlewarerecipe in the quickstart, closing the discoverability follow-on from TRA-787 F2. Sweep audit:http-method-coverage.mdalready cross-links the recipe; other PATCH mentions are generic contract statements, not stack-specific.Test plan
pnpm buildclean (no broken links or render errors)pnpm typecheckcleanpnpm dlx prettier --writeapplied to edited files/docs/api/authenticationon preview — tag rows visible underassets:write/locations:write; inheritance bullet present; canonical-source note above the table; 401 detail table renders cleanly/docs/api/design-noteson preview — bodySerializer cross-link resolves to/docs/api/quickstart#openapi-fetch🤖 Generated with Claude Code