Public API Contract Style Guide

Public API Contract Style Guide

This is the normative style guide for batoi.public-api/1. Published operation contracts may narrow these rules, but cannot weaken their security or compatibility boundaries.

Transport and media type

• Send POST https://batoi.com/api/.
• Send Content-Type: application/json and accept JSON.
• Keep the complete request body at or below 1 MiB.
• Use https://www.batoi.com/api/ only where configured-host compatibility is required.
• Browser origins are denied unless the gateway declares an exact approved origin or same-origin policy.

Authentication and identity

• Send X-Batoi-Client-Id and Authorization: Bearer <credential>.
• The credential is bound to one workspace gateway, environment, audience, scope set, lifecycle state, and optional expiry.
• Do not put new credentials in the JSON body. api_key and security_key body fields are legacy-only and receive deprecation and sunset headers.

Request envelope

The strict top-level fields are:

• contract: batoi.public-api/1;
• gateway: immutable logical gateway UID;
• operation: published operation key;
• environment: sandbox, beta, or production;
• method: logical method declared by the operation;
• request: strict operation-specific object;
• idempotency_key: compatibility field only where a client cannot send Idempotency-Key; headers are preferred.

Callers cannot supply internal routes, handlers, tables, workspace IDs, Project IDs, App IDs, evidence references, or provider targets.

Schemas and collections

• Request and response schemas are immutable within a contract hash.
• Object schemas reject undeclared properties.
• Pagination and filter fields exist only when the operation schema declares them.
• Collection limits must be bounded and deterministic.
• Schema or target drift after approval makes the operation unavailable until a new contract is reviewed and published.

Response envelope

Successful published responses include:

• success, contract, gateway, and operation;
• contract_version and contract_hash;
• correlation_id and UTC timestamp;
• schema-validated data.

The response headers include X-Request-ID, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Errors and retries

Errors include success: false, stable error.code, safe error.message, UTC timestamp, and request_id. They never include stack traces, credentials, private contract definitions, or unrestricted payloads.

• Do not retry 400, 401, 403, 404, 405, 409, 413, or 415 without correcting the request or policy state.
• A 429 includes Retry-After; use bounded exponential backoff with jitter.
• Retry selected transient 5xx responses only with a bounded attempt count.

Idempotency and replay

Every future non-read operation requires Idempotency-Key. A key is bound to one client binding and operation. Reusing it for the same logical attempt returns the recorded result; conflicting or gateway-level replays fail closed.

Versioning and lifecycle

Contract hashes are immutable. A new activation deprecates the previous environment version and retains it as a rollback target when available. The first activation uses immediate fail-closed revocation as its recovery mode.

Deprecation is communicated through contract documentation and, for legacy body credentials, Deprecation, Sunset, and deprecation Link headers. Revocation for a security event may be immediate.