HTTP inputs, outputs and errors
A Toolora HTTP contract is defined by its registered route, parameter/body models, dependencies, service or RPC result and error mapping. FastAPI’s generated schema describes declared HTTP shapes; business rules and resource authority also depend on the implementation below that shape.
The committed endpoint-security catalogue records methods, paths and declared policy categories. It does not replace request models, business validation or response semantics. Public MCP tools have a separate tool contract rather than inheriting a similar HTTP route’s schema.
Contract sources
Section titled “Contract sources”| Contract element | Owning source | Interpretation |
|---|---|---|
| Mounted path and method | server.py router registration and route decorator |
Most application routers are under /api; MCP/runtime/internal entries have their own registration |
| Path/query input | Function annotations, Query and domain parsers |
UUIDs, limits and accepted selections vary by operation |
| Body input | Pydantic operation model and explicit validation | Required fields, numeric precision and collection bounds; unknown-field policy depends on the model |
| Authority | Dependencies, dedicated admission and resource checks | A valid shape is not permission |
| Transaction input/result | Domain service and database RPC | Revision, fingerprint, replay and atomicity semantics |
| Provider JSON boundary | postgrest_payload helpers where used |
A successful transport must still have the expected row/object/scalar shape |
| Error result | Route exception mapping and shared handlers | Status plus detail; provider certainty must be interpreted separately |
Some routes declare precise response models; others return typed or dynamic dictionaries, projections, binary responses or per-item receipts. Do not infer a single application-wide result envelope. TypeScript assertions in frontend contracts are not runtime validation of the response.
Concrete allocation input
Section titled “Concrete allocation input”PUT /api/purchase-costs/{invoice_id}/allocations takes a UUID path and SaveCosts. At this revision, it requires a nonnegative expected_revision, a 32-character lowercase hexadecimal basis_fingerprint, at most 500 allocation rows, and a nullable duplicate target. duplicate_checked defaults to false.
Each row has a 1–100 character source key, a description up to 500 characters, an amount with up to 14 digits and two decimal places, and nullable project/overhead-account UUIDs. Parsing these fields is only the first step: the RPC checks source basis, allowed targets, amounts and duplicate rules. A syntactically valid project ID from another company is still invalid for the operation.
A quote draft uses a different revision contract: its expected update timestamp is parsed by the route and passed with supported fields, line edits and optional recipient replacement. There is no global revision field that a client can copy between APIs.
Complete and bounded reads
Section titled “Complete and bounded reads”PostgREST can cap rows independently of a requested range. The shared complete-read helper advances by actual returned rows, uses stable caller-owned ordering and probes its safety boundary. Its defaults are 100 rows per request and a 200,000-row complete-read limit. An exceeded complete-read limit raises rather than presenting partial data as complete.
Other endpoints intentionally page or return bounded projections. Counts, continuation fields and source coverage must be interpreted according to that operation. An empty page is not proof that the entire register is empty. Customer admission uses scalar JSON RPC sets to avoid treating a row-capped authorization result as a complete grant set.
Errors and a synthetic example
Section titled “Errors and a synthetic example”A stale allocation produces 409; invalid domain input commonly produces 422; an out-of-scope invoice can produce 404 without exposing another company’s record. The API’s complete-read failure returns 503 with a request to narrow the query. Shared unhandled failures return a generic 500 detail instead of raw exception contents.
A synthetic client submitting revision 7 with valid row shapes must still handle a concurrent revision 8 and retain its proposal. Reposting with 8 without review is not a schema correction. Error diagnosis distinguishes conflict recovery from provider uncertainty.
The source review identifies these exact models and boundaries. Runtime schema, route tests and database tests each prove their own named inputs; no universal validation or compatibility guarantee is inferred from generated documentation.