references/data-api-contracts.md

# Data, API and Integration Contracts

Start from user actions and business invariants, not just database tables. Identify entities, ownership, identifiers, cardinalities, lifecycle, retention/deletion, audit events and tenant boundaries.

API contracts specify purpose, auth scopes, input/output schemas, errors, pagination, rate limits, idempotency, retry semantics and versioning. Define conflicting writes and incomplete states. A destructive flow must include preview/confirmation when appropriate.

Schema changes require migrations, backward compatibility checks, rollbacks and backfills appropriate to risk. External services need authentication, quotas, failure behavior, customer-data boundaries and compliance checks.

Never pretend that an endpoint or schema exists without reading its implementation or authoritative specification.