Design an API contract

An API contract is a promise that outlives its first implementation: once clients depend on it, every field name, error shape and default is expensive to change. Designing the contract first, from the consumers' point of view, catches the expensive mistakes while they are still cheap to fix.

Design the API contract for: [CAPABILITY] Only if [CONSUMERS] is given: Consumers and their constraints: [CONSUMERS] Only if [CONVENTIONS] is given: Existing conventions to follow exactly: [CONVENTIONS] Style: auto. If it is auto, choose REST, GraphQL or gRPC and justify the choice in one sentence based on the consumers.

1. Restate the capability as the operations consumers need, phrased from their side ("list my open orders", not "query the orders table").
2. Model the resources (or types, or services) and the operations on them. Keep names consistent, plural for collections, and free of internal storage details.
3. Define every request and response schema: field names, types, required or optional, formats and constraints (length, range, enum values). Use opaque string ids, RFC 3339 UTC timestamps, and money as an integer amount in minor units plus an ISO 4217 currency code, unless the conventions say otherwise.
4. Define the error model: one consistent shape (for HTTP, RFC 9457 problem details unless the conventions differ), the status or error codes each operation can return, and which errors are safe to retry.
5. Add the cross-cutting behaviour that applies: pagination for lists (cursor-based by default), filtering and sorting, idempotency keys for operations that create or charge, optimistic concurrency (ETag and If-Match, or a version field) for updates, authentication and authorization scopes per operation, and rate limits.
6. Write the evolution rules: what counts as a compatible change, how breaking changes are versioned, and how fields are deprecated.

• Design the contract only. No server implementation code.
• Do not invent business rules (limits, states, permissions, pricing). When the contract needs one that was not given, choose a placeholder, mark it as an assumption and list it under Assumptions and open questions.
• Follow the given conventions over these defaults whenever they conflict.
• Include one realistic request and response example for each main operation.
• Prefer fewer, well-shaped operations over one endpoint per screen.
• Separate what you verified from what you inferred. Mark inferences as such.
• When you do not know, say "I don't know" once and state what would settle it.

Summary

Style chosen and why, the resources, and the main design choices, in at most 6 lines.

Operations

Table: operation, method and path (or query, mutation or RPC name), purpose, auth scope, idempotent (yes or no).

Contract

One fenced block with the machine-readable contract: OpenAPI 3.1 YAML for REST, SDL for GraphQL, proto3 for gRPC. Include the examples.

Errors

Table: code, when it happens, retryable (yes or no).

Evolution and compatibility

Bullets.

Assumptions and open questions

Numbered. Each assumption says what it affects.