Repository navigation
Harden the request contract and tell composition failures apart in previews - #4
Merged
Merged
Conversation
…eviews
A team running the TypeScript sibling behind its own authentication reported
contract gaps that this implementation shared. The contract changes land here
first, since openapi.yaml is generated from these routes.
- Request bodies: a request declaring a JSON media type must carry a valid
JSON object (an empty body there is a 400); one declaring no media type or
another one counts as omitted when empty and is a 400 otherwise. Ninja read
any body as JSON, and answered malformed JSON outside the error envelope.
- Every 400 carries details.issues, including malformed JSON, a body in the
wrong media type, an invalid path version and a refusal from the library.
- /versions/{version} validates the version (>= 1) and declares its 400.
- Preview composes first: a broken chain is TEMPLATE_COMPOSITION_ERROR, as on
GET /composition, and a store failure while composing is a generic 500
rather than a 409 carrying the backend's message.
- GET /composition reads the version once.
- hasMore means the next page has a row.
- FORBIDDEN (403) is a new code, declared on every authenticated route.
- POST /versions declares its body optional; the status filter documents how
it combines with mostRecentActiveVersion.
- Every response a test receives is checked against the statuses its route
declares.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 9, 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
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 team running the TypeScript sibling of this API in a healthcare app (behind their own authentication) reported a set of contract gaps and bugs. Most existed here too. The contract is normative and generated from this repository, so its changes land here first; the TypeScript implementation copies the regenerated
openapi.yaml.Contract (
openapi.yaml)/versions/{version}:GETandDELETEvalidate the version as a positive integer and declare the 400.0and-1used to be 404s.409 TEMPLATE_COMPOSITION_ERROR(the answerGET /compositiongives), one that composes but fails to render stays409 PREVIEW_UNAVAILABLE, and a store failure while composing is a generic 500 through the unhandled-error hook. It used to reach the client as a 409 carrying the backend's message.application/json(orapplication/*+json) must carry a valid JSON object, so an empty body there is a 400. A request declaring no media type or another one counts as an omitted body when empty, and is a 400 otherwise. Ninja read any body as JSON and answered malformed JSON as{"detail": …}outside the envelope.details.issues: [{ path, message }].hasMoremeans the next page has at least one row.POST /templates/{key}/versionsdeclares its body optional.FORBIDDEN(403): new code, declared on every authenticated route, for hosts that authenticate callers themselves. This server does not produce it yet.statusfilter: documents thatmostRecentActiveVersion=falseis needed to find inactive or archived versions.Other
GET /compositionreads the version once (ServiceCaller.compose_templatereplacesget_composed_template).Testing
export_openapi --check.Release
Behaviour change for clients sending bodies without
Content-Type: application/json; see the 3.3.0 release notes in thevintasendrepository.Related PRs
Python
TypeScript
Python: merge the two API PRs, then the release notes. TypeScript: merge the package PRs, then vintasoftware/vintasend-ts#15, then run the release.
🤖 Generated with Claude Code