# API HTTP mappings

`pnpm generate:contracts` generates the API's HTTP structs and mechanical
Protobuf conversions. `pnpm check:api` checks enrolment and output drift.

Every Beto request owner consumed by the API that has an HTTP contract needs
`<owner>.json` here. A request consumer with no HTTP contract needs no HTTP
mapping. The check detects an absent mapping file even if its generated output
was also removed. Party Governance uses the existing specialised
`scripts/generate_api_party.py` through the same check, preserving its profile
presence and eligibility validation.
Its schema-level `x-direction: request` generates presence-preserving `ToWire`
methods for full profile replacement; required fields must agree with the owner
annotations. Profile responses contain only user-edited fields and their revision.

Each entry names an HTTP `schema`, its owner-local Protobuf `message`, and an
explicit HTTP-field-to-wire-field `fields` map. Every object schema in the
owner's `http_api/schemas.json` must be enrolled. Top-level arrays refer to an
enrolled object; they need no separate wire DTO. Nested objects and repeated
fields refer to mappings of the same direction. Unsupported shapes fail before
writing any outputs.

The default direction is `response`: generate `<Schema>FromWire`, reject missing
objects and integers outside the browser's exact range, preserve nullable fields, reject absent fields annotated `required_output`,
and return empty collections as JSON arrays. `"direction": "request"` generates
`<Schema>ToWire` for command bodies. Required fields must agree with Protobuf's
`required_input` annotations. Pointer fields preserve absent and explicit empty
values; missing required values fail conversion. The HTTP boundary still validates
OpenAPI constraints and rejects unknown fields before conversion.

Generated files live under `../generated/<owner>/`. Keep authentication, actor and
path selection, command identity, transport envelopes, error-to-status decisions
and business validation in the handwritten API bindings. Enrolment grants no
route or broker authority.