api-design

This skill provides comprehensive guidance for designing RESTful APIs following industry best practices.

Core Principles

1. Resource-Oriented Design

• Use nouns for resource names (e.g., /users, /products)
• Avoid verbs in URLs
• Use HTTP methods to represent actions

2. HTTP Methods

• GET: Retrieve resources
• POST: Create new resources
• PUT: Update entire resources
• PATCH: Partial updates
• DELETE: Remove resources

3. URL Structure

GET    /api/v1/users          - List all users
GET    /api/v1/users/{id}     - Get specific user
POST   /api/v1/users          - Create new user
PUT    /api/v1/users/{id}     - Update user
DELETE /api/v1/users/{id}     - Delete user

4. Response Format

• Use JSON as default format
• Use camelCase for field names
• Include metadata (pagination, timestamps)

5. Error Handling

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "User ID must be a positive integer",
    "details": []
  }
}

6. Status Codes

• 200: Success
• 201: Created
• 400: Bad Request
• 401: Unauthorized
• 404: Not Found
• 500: Internal Server Error

Best Practices

• Version your APIs
• Use pagination for list endpoints
• Implement rate limiting
• Document with OpenAPI/Swagger