api-design

API Design

Overview

Design APIs that are consistent, predictable, and well-documented. This skill covers REST and GraphQL API design patterns.

Core principle: APIs are contracts. Once published, breaking changes are expensive.

When to Use

Use this skill:

• Designing new API endpoints
• Refactoring existing APIs
• Adding versioning strategy
• Creating OpenAPI/GraphQL specifications
• Standardizing error responses

Not needed for:

• Internal function signatures
• Database schema design (use data-engineer agent)

REST API Design

Resource Naming

✅ Good                          ❌ Bad
-----------------------------------------
GET  /users                      GET  /getUsers
GET  /users/{id}                 GET  /user?id=123
POST /users                      POST /createUser
PUT  /users/{id}                 POST /updateUser
DELETE /users/{id}               GET  /deleteUser/{id}
GET  /users/{id}/orders          GET  /getUserOrders

Rules:

• Use nouns, not verbs (HTTP method is the verb)
• Plural for collections: /users not /user
• Hierarchical for relationships: /users/{id}/orders
• Lowercase, hyphen-separated: /user-profiles not /userProfiles

HTTP Methods

Method	Purpose	Idempotent	Safe
GET	Retrieve resource	Yes	Yes
POST	Create resource	No	No
PUT	Replace resource	Yes	No
PATCH	Partial update	Yes*	No
DELETE	Remove resource	Yes	No

*PATCH is idempotent if using JSON Patch/Merge Patch format.

Status Codes

2xx Success
-----------------------------------------
200 OK              - GET/PUT/PATCH success, body contains data
201 Created         - POST success, Location header has URL
204 No Content      - DELETE success, no body

4xx Client Error
-----------------------------------------
400 Bad Request     - Invalid input (validation failed)
401 Unauthorized    - Authentication required
403 Forbidden       - Authenticated but not allowed
404 Not Found       - Resource doesn't exist
409 Conflict        - State conflict (duplicate, version mismatch)
422 Unprocessable   - Valid syntax but semantic error

5xx Server Error
-----------------------------------------
500 Internal Error  - Unexpected server error
502 Bad Gateway     - Upstream service failed
503 Unavailable     - Temporary overload