API sketch

Sketch APIs early to align clients, services, and data model. List key REST or RPC endpoints, event types, request/response shapes, pagination cursors, idempotency keys for writes, auth context, and error codes. Events complement APIs for async workflows.

Keep contracts coarse in interviews — resource names, critical fields, and consistency notes — not OpenAPI line by line. Mention versioning strategy if mobile clients lag server releases.

On interviews: define three to five core endpoints for the prompt, show idempotency for payment-like operations, and note pagination for list APIs.

Common pitfalls: chatty APIs requiring many round trips; no idempotency on create/charge endpoints; ambiguous error handling for retries.

The trade-off is flexibility versus complexity—know when the simpler path is enough.

Checklist:

• List core endpoints or events.
• Mark idempotent versus non-idempotent writes.
• Specify pagination and auth per resource.
• Note error shapes safe for client retries.