platform-api-contract

To enforce a single OpenAPI contract, you must use docs/contracts/openapi.yaml as the single source of truth, requiring stable operationIds and reusable schemas. This prevents frontend, backend, and API drift by making the Platform HTTP API contract explicit and enforceable.

Isolating internal endpoints from public OpenAPI definitions requires defining strict boundaries for public /api/** resources. You must prevent /internal/**, /orchestrator/**, and /a2a/** endpoints from leaking into the public OpenAPI contract to maintain secure API separation.

Standardizing error envelopes and HTTP status codes in API contract testing involves defining strict success and error response structures. The contract enforces specific error code domains and HTTP status strategies to guarantee authentication and object-level permission consistency across the gateway.

Yes, you can generate frontend API client types directly from the OpenAPI contract. The contract specifies that frontend API clients and types must be OpenAPI-generated, ensuring strict consistency between the gateway handlers and the frontend models.

Verifying gateway handler responses with contract tests involves using mocks to validate authentication, permissions, and error responses. Contract tests strictly check that handlers do not return any fields undefined by the OpenAPI schema, ensuring output consistency.

Contract tests fail when API responses return undefined OpenAPI fields because the contract enforces strict handler output consistency. This mechanism ensures the gateway only returns data explicitly defined in the OpenAPI schema, preventing unexpected frontend type mismatches and drift.