API Design Skill

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