# API Contract Designer Skill ## Objective Design an API contract that is intuitive for consumers, easy to version, and consistent across resources. ## Design Checklist ### 1. Resource Modelling - Use nouns for resources, verbs for actions: `/orders` not `/getOrders` - Nested resources max 2 levels: `/orders/{id}/items` ✓; `/users/{id}/orders/{id}/items/{id}/reviews` ✗ - Plural for collections, singular for singletons ### 2. HTTP Semantics | Method | Use case | Idempotent | Safe | |--------|----------|-----------|------| | GET | Read | ✓ | ✓ | | POST | Create / non-idempotent action | ✗ | ✗ | | PUT | Full replace | ✓ | ✗ | | PATCH | Partial update | ✓* | ✗ | | DELETE | Remove | ✓ | ✗ | ### 3. Response Conventions - Always return `{ data, meta, errors }` envelope - Use HTTP status codes correctly (201 Created, 204 No Content, 422 Unprocessable) - Error response: `{ code, message, field?, docs_url }` - Pagination: cursor-based for large/real-time data; offset for small static datasets ### 4. Versioning Strategy - URL versioning (`/v1/`) for major breaking changes - Header versioning (`Accept: application/vnd.api+json;version=2`) for minor variants - Deprecation: 6-month notice, `Deprecation` + `Sunset` response headers ### 5. Security - AuthN: Bearer token (JWT) in Authorization header — never in URL - Rate limiting: return `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `Retry-After` - Sensitive fields: never in GET params (they appear in logs) ## Output Format 1. Resource list with CRUD matrix 2. OpenAPI 3.1 YAML skeleton for each endpoint 3. Error code registry 4. Versioning decision + migration guide