api-design

API Design

Purpose: Design robust, maintainable, and user-friendly REST APIs. Focus: Resource naming, HTTP methods, status codes, versioning, documentation. Note: Language-agnostic patterns applicable to any tech stack.

When to Use This Skill

• Designing new REST API endpoints
• Implementing pagination, filtering, or sorting
• Adding rate limiting or CORS configuration
• Documenting APIs with OpenAPI/Swagger
• Designing webhook notification systems

Prerequisites

• HTTP protocol fundamentals
• JSON data format understanding

Decision Tree

Designing an API endpoint?
+- What operation?
| +- Read data -> GET (idempotent, cacheable)
| +- Create resource -> POST (returns 201 + Location header)
| +- Full update -> PUT (idempotent, replaces entire resource)
| +- Partial update -> PATCH (only changed fields)
| - Remove -> DELETE (idempotent, returns 204)
+- Returns collection?
| - Add pagination (cursor or offset) + filtering + sorting
+- Versioning needed?
| +- URL path versioning -> /api/v1/resources (recommended)
| - Header versioning -> Accept: application/vnd.api.v1+json
+- Error handling?
| - RFC 7807 Problem Details with proper HTTP status codes
- Security?
 +- Public? -> Rate limiting + API key
 - Private? -> OAuth2/JWT + scopes

RESTful Conventions

Resource Naming

[PASS] Good:
GET /api/v1/users # List users
POST /api/v1/users # Create user
GET /api/v1/users/{id} # Get specific user
PUT /api/v1/users/{id} # Update user (full)
PATCH /api/v1/users/{id} # Update user (partial)
DELETE /api/v1/users/{id} # Delete user

GET /api/v1/users/{id}/orders # Get user's orders (nested)
POST /api/v1/users/{id}/orders # Create order for user

[FAIL] Bad:
GET /api/v1/get_users
POST /api/v1/create_user
GET /api/v1/user_detail?id=123
POST /api/v1/users/delete/{id} # Use DELETE method instead

Resource Naming Rules

• Use nouns, not verbs (users, not getUsers)
• Use plural form (users, not user)
• Use kebab-case for multi-word resources (order-items)
• Keep URLs lowercase
• Use nesting for relationships (users/{id}/orders)
• Limit nesting to 2 levels maximum