api-design

API Design Skill

Overview

Best practices and patterns for designing robust, scalable, and developer-friendly REST APIs.

Capabilities

• RESTful API design patterns
• HTTP methods and status codes
• API versioning strategies
• Authentication and authorization
• Error handling
• API documentation (OpenAPI/Swagger)

---

RESTful Design Principles

Resource-Oriented URLs

✅ Good RESTful Design:
GET    /api/users              - List all users
GET    /api/users/123          - Get user with ID 123
POST   /api/users              - Create new user
PUT    /api/users/123          - Update user 123
PATCH  /api/users/123          - Partially update user 123
DELETE /api/users/123          - Delete user 123

GET    /api/users/123/orders   - Get orders for user 123
POST   /api/users/123/orders   - Create order for user 123

❌ Bad: Verb-based URLs:
GET    /api/getUser?id=123
POST   /api/createUser
POST   /api/deleteUser/123

HTTP Methods

Method	Purpose	Idempotent	Safe	Request Body	Response Body
GET	Retrieve resource	Yes	Yes	No	Yes
POST	Create resource	No	No	Yes	Yes
PUT	Replace resource	Yes	No	Yes	Yes
PATCH	Update resource	No	No	Yes	Yes
DELETE	Delete resource	Yes	No	No	Optional

---

HTTP Status Codes

Success Responses (2xx)

• 200 OK: Request succeeded (GET, PUT, PATCH)
• 201 Created: Resource created (POST)
• 204 No Content: Success with no body (DELETE)

Client Errors (4xx)

• 400 Bad Request: Invalid request data
• 401 Unauthorized: Authentication required
• 403 Forbidden: Authenticated but not authorized
• 404 Not Found: Resource doesn't exist
• 409 Conflict: Conflict with current state (e.g., duplicate)
• 422 Unprocessable Entity: Validation failed
• 429 Too Many Requests: Rate limit exceeded

Server Errors (5xx)

• 500 Internal Server Error: Generic server error
• 502 Bad Gateway: Upstream service error
• 503 Service Unavailable: Service temporarily down
• 504 Gateway Timeout: Upstream service timeout