Skip to content

Harden the request contract and tell composition failures apart in previews - #4

Merged
hugobessa merged 1 commit into
mainfrom
feat/contract-hardening
Oct 9, 2026
Merged

hugobessa merged 1 commit into
mainfrom
feat/contract-hardening

Conversation

@hugobessa

@hugobessa hugobessa commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

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)

  • 400 on /versions/{version}: GET and DELETE validate the version as a positive integer and declare the 400. 0 and -1 used to be 404s.
  • Preview errors: a template that cannot be composed is a 409 TEMPLATE_COMPOSITION_ERROR (the answer GET /composition gives), one that composes but fails to render stays 409 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.
  • Request bodies: a request declaring application/json (or application/*+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.
  • One 400 envelope: every 400 carries details.issues: [{ path, message }].
  • hasMore means the next page has at least one row.
  • POST /templates/{key}/versions declares 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.
  • status filter: documents that mostRecentActiveVersion=false is needed to find inactive or archived versions.

Other

  • GET /composition reads the version once (ServiceCaller.compose_template replaces get_composed_template).
  • The test client fails any test that receives a 4xx its route does not declare.

Testing

  • 313 tests, 97.5% coverage, ruff, mypy, export_openapi --check.
  • The 35 new tests fail against the previous code.

Release

Behaviour change for clients sending bodies without Content-Type: application/json; see the 3.3.0 release notes in the vintasend repository.

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

…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant