api

Evolve in place with additive changes: new optional fields, parameters, headers, or endpoints that old callers can ignore. For renames, removals, or required additions, ship a successor contract under a new version with a deprecation overlap window and Sunset headers.

Pick status by failure origin: 4xx when the consumer can fix the request (400 malformed, 401 unauthenticated, 403 forbidden, 422 domain-rule violation), and 5xx for upstream or service faults (502, 503, 504). Never leak raw upstream or internal errors to consumers.

Default to JSON:API for resource-oriented REST APIs, which uses a top-level errors array with string status and source pointers. Use RFC 9457 Problem Details for plain JSON APIs and FHIR OperationOutcome for healthcare. Pick one shape per API; the conventions are structurally distinct and not interchangeable.

Define an idempotency-key contract specifying key scope, replay window, duplicate-response behavior, and conflict semantics. The server persists key-to-response mappings, claims keys atomically, and rejects same-key different-body requests with a documented conflict status.

Middleware handles transport-wide concerns like logging, tracing, CORS, body parsing, and authentication context. Endpoint-specific validation, resource ownership checks, privileged authorization, and domain invariants belong in the handler or domain layer where the resource and actor are visible.

No. This Skill covers REST resource APIs only. gRPC, GraphQL, and message-queue contracts have their own ecosystem conventions for contract shape, errors, and evolution, which are explicitly out of scope.