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