api-design

RESTful API design best practices and conventions guide

⭐182stars🔀32forks📁View on GitHub🕐Updated Jan 1, 2026

When & Why to Use This Skill

This Claude skill provides a comprehensive guide for designing RESTful APIs, offering expert guidance on resource-oriented design, HTTP method implementation, and standardized response formats to build scalable and maintainable web services.

Use Cases

  • API Architecture Planning: Designing clean and intuitive URL structures and resource hierarchies for new software projects.
  • Standardizing Development: Establishing consistent naming conventions, camelCase field usage, and unified error handling across engineering teams.
  • Documentation and Compliance: Ensuring API designs align with industry standards like OpenAPI/Swagger and implement correct HTTP status codes for better client-side integration.
nameapi-design
descriptionRESTful API design best practices and conventions guide

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