api-design-assistant

API Design Assistant

Overview

Assist with designing well-structured, RESTful APIs by suggesting endpoints, parameters, return types, and best practices. Generate OpenAPI specifications and provide implementation guidance.

Workflow

1. Understand Requirements

When designing a new API or reviewing an existing one, first understand:

For new API design:

• What is the domain/purpose of the API?
• What resources need to be exposed? (users, products, orders, etc.)
• What operations are needed? (create, read, update, delete, custom actions)
• Who are the consumers? (web app, mobile app, third-party integrations)
• Are there specific requirements? (authentication, rate limiting, versioning)

For API review:

• What are the existing endpoints?
• What issues or improvements are needed?
• Are there consistency problems?
• Are best practices being followed?

2. Design or Review API Structure

Follow these steps based on the use case:

Designing New APIs

Step 1: Identify Resources

Map domain concepts to API resources:

• User management → /users
• Product catalog → /products
• Order processing → /orders
• User's orders → /users/{userId}/orders

Step 2: Define Endpoints

For each resource, determine needed operations:

# Users resource
GET    /users              # List users
POST   /users              # Create user
GET    /users/{id}         # Get specific user
PUT    /users/{id}         # Replace user
PATCH  /users/{id}         # Update user
DELETE /users/{id}         # Delete user

# Nested resources
GET    /users/{id}/orders  # Get user's orders
POST   /users/{id}/orders  # Create order for user

# Actions
POST   /users/{id}/activate      # Activate user
POST   /orders/{id}/cancel       # Cancel order

Step 3: Design Request/Response Schemas

Define what data each endpoint expects and returns. See best-practices.md for detailed examples.

Step 4: Add Supporting Features

• Authentication (Bearer tokens, API keys)
• Pagination (page-based, cursor-based)
• Filtering and sorting
• Error handling
• Versioning strategy