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](references/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

**Step 5: Generate OpenAPI Specification**

Create formal API documentation. See [openapi-template.md](references/openapi-template.md) for complete templates.

#### Reviewing Existing APIs

**Step 1: Analyze Consistency**

Check for:
- Consistent naming conventions
- Consistent use of HTTP methods
- Consistent response formats
- Consistent error handling

**Step 2: Identify Issues**

Common problems:
- Verbs in URLs (e.g., `/getUsers` instead of `GET /users`)
- Wrong HTTP methods (e.g., GET for mutations)
- Inconsistent naming (e.g., `/user` vs `/users`)
- Missing pagination on collections
- Inadequate error responses
- No versioning strategy

**Step 3: Suggest Improvements**

Provide specific recommendations:
- "Change `/getUsers` to `GET /users`"
- "Add pagination to `GET /users` endpoint"
- "Standardize error response format across all endpoints"
- "Use PATCH instead of PUT for partial updates"

**Step 4: Propose Migration Path**

If breaking changes are needed:
- Version the API (`/v2/users`)
- Provide deprecation timeline
- Suggest backward compatibility approaches

### 3. Apply Best Practices

Consult [best-practices.md](references/best-practices.md) for detailed guidance on:

- **Resource naming**: Plural nouns, lowercase, hyphens
- **HTTP methods**: Correct usage of GET, POST, PUT, PATCH, DELETE
- **Status codes**: When to use 200, 201, 204, 400, 401, 403, 404, 409, 422, 429, 500
- **Authentication**: Bearer tokens, API keys, OAuth2
- **Pagination**: Offset, page-based, cursor-based
- **Filtering & sorting**: Query parameter patterns
- **Versioning**: URL, header, or query parameter approaches
- **Error handling**: Consistent error response formats
- **Rate limiting**: Header-based communication

### 4. Generate Documentation

Depending on user needs, provide:

#### Markdown Documentation

```markdown
## POST /users

Create a new user account.

### Request

**Headers:**
- `Content-Type: application/json`
- `Authorization: Bearer <token>`

**Body:**
```json
{
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user"
}
```

### Response

**Success (201 Created):**
```json
{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "role": "user",
  "created_at": "2024-01-15T10:30:00Z"
}
```

**Error (400 Bad Request):**
```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Email format is invalid"
      }
    ]
  }
}
```
```

#### OpenAPI 3.0 Specification

Generate formal OpenAPI specs using templates from [openapi-template.md](references/openapi-template.md).

#### Implementation Hints

Provide language/framework-specific guidance when requested:

**Example for Express.js:**
```javascript
// POST /users
app.post('/users', async (req, res) => {
  try {
    const { name, email, role } = req.body;

    // Validation
    if (!name || !email) {
      return res.status(400).json({
        error: {
          code: 'VALIDATION_ERROR',
          message: 'Name and email are required'
        }
      });
    }

    // Create user
    const user = await User.create({ name, email, role });

    res.status(201)
      .location(`/users/${user.id}`)
      .json(user);
  } catch (error) {
    res.status(500).json({
      error: {
        code: 'INTERNAL_ERROR',
        message: 'Failed to create user'
      }
    });
  }
});
```

### 5. Handle Common Scenarios

#### Pagination

Recommend appropriate pagination strategy:
- **Small datasets**: Offset or page-based
- **Large datasets**: Cursor-based
- **Real-time data**: Cursor-based with timestamps

#### Authentication

Suggest authentication approach:
- **Public API**: API keys
- **Web/mobile apps**: JWT tokens
- **Third-party integrations**: OAuth2
- **Internal services**: mTLS or service tokens

#### Versioning

Recomme