SKILL.md
503 lines · 1,801 words
API Designer
Purpose
Design consistent, intuitive, and evolvable HTTP APIs. This skill covers REST API design from resource modeling through error handling, pagination, versioning, and documentation with OpenAPI. GraphQL design considerations are included for comparison and hybrid architectures.
REST Maturity Model (Richardson)
Level 0: The Swamp of POX
- Single endpoint, single HTTP method (POST)
- RPC-style: POST /api { "action": "getUser", "id": 123 }
- Avoid this.
Level 1: Resources
- Multiple endpoints, one per resource
- POST /users, POST /users/123/delete
- Still misusing HTTP methods.
Level 2: HTTP Verbs (TARGET for most APIs)
- Resources + correct HTTP methods
- GET /users, POST /users, PUT /users/123, DELETE /users/123
- Correct status codes (200, 201, 204, 400, 404, etc.)
Level 3: HATEOAS (Hypermedia)
- Level 2 + hypermedia controls in responses
- Clients discover actions from response links
- Full REST (rarely implemented in practice)