Description
Full API contract: resource models, error contracts, pagination, idempotency with RFC references.
Design an API contract before writing implementation. The contract is the source of truth—client and server build independently against it. Every ambiguity becomes a production bug. 1. RESOURCE MODEL (JSON Schema draft-07) Every field: type, required (only essentials), nullable (distinguish absent vs explicitly null), constraints (minLength, maxLength, pattern for email/UUID/date-time, enum), and a realistic example. 2. STATE TRANSITIONS - POST: creates new resource. Client provides some fields, server generates id/createdAt. - PATCH: partial update. Choose JSON Merge Patch (RFC 7396, simpler) or JSON Patch (RFC 6902, atomic multi-op). Justify choice. - PUT: full replacement. Only when client has full authority over resource state. 3. ERROR CONTRACT — consistent shape: ```json {"error":{"code":"VALIDATION_ERROR","message":"description", "details":[{"field":"email","issue":"must be valid","value":"bad"}], "requestId":"req_abc"}} ``` Status mapping: 400=VALIDATION_ERROR, 401=UNAUTHORIZED, 403=FORBIDDEN, 404=NOT_FOUND, 409=CONFLICT, 429=RATE_LIMITED, 500=INTERNAL_ERROR. 4. PAGINATION: Cursor-based (stable under live data, best for feeds/logs) or offset-based (simpler, supports page jumps, breaks under insertion/deletion). Justify. 5. IDEMPOTENCY: SAFE (GET/HEAD), IDEMPOTENT (PUT/DELETE), NON-IDEMPOTENT (POST—use Idempotency-Key: UUID header). OUTPUT: Complete contract in markdown with curl example per endpoint and ASCII sequence diagram.
No comments yet. Be the first!