| name | api-design |
| description | Design robust, consistent, and developer-friendly APIs. |
Skill: API Design
Category: Backend Engineering
Priority: High
Description
Design robust, consistent, and developer-friendly APIs.
Purpose
Create APIs that are easy to understand, hard to misuse, and resilient to change.
Trigger
Use this skill when:
- Designing a new API
- Adding endpoints to an existing API
- Versioning an API
- Writing API documentation
- Reviewing API changes
Context
- Consumer requirements
- Authentication method
- Rate limiting needs
- Data volume and latency requirements
Workflow
- Resource Modeling - Identify nouns (resources), not verbs (actions).
- Consistent Naming - Use plural nouns, kebab-case for paths.
- Use Standard Methods - GET, POST, PUT, PATCH, DELETE correctly.
- Status Codes - Use appropriate HTTP status codes.
- Versioning - Include version in URL or header.
- Pagination - Always paginate list endpoints.
- Filtering & Sorting - Standard query parameters.
- Error Responses - Consistent structure, helpful messages.
- Rate Limiting - Protect the server and consumers.
- Documentation - OpenAPI/Swagger specification.
Examples
Good API Design
GET /api/v1/users?page=1&limit=20&sort=-created_at
GET /api/v1/users/:id
POST /api/v1/users
PATCH /api/v1/users/:id
DELETE /api/v1/users/:id
GET /api/v1/users/:id/orders?status=pending
Bad API Design
GET /api/getUserData?id=123
POST /api/createNewUserRecord
GET /api/users/123/orders/getAllPendingOrders
Anti-patterns
- Verbs in URLs
- Inconsistent naming
- Missing pagination
- Breaking changes without versioning
- Vague error messages
Verification
References