api-design-assistant

name

api-design-assistant

description

Design and review APIs with suggestions for endpoints, parameters, return types, and best practices. Use when designing new APIs from requirements, reviewing existing API designs, generating API documentation, or getting implementation guidance. Supports REST APIs with focus on endpoint structure, request/response schemas, authentication, pagination, filtering, versioning, and OpenAPI specifications. Triggers when users ask to design, review, document, or improve APIs.

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

Step 5: Generate OpenAPI Specification

Create formal API documentation. See 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 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

## POST /users

Create a new user account.

### Request

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

**Body:**
```json
{
  "name": "John Doe",
  "email": "[e-mail]",
  "role": "user"
}

Response

Success (201 Created):

{
  "id": 123,
  "name": "John Doe",
  "email": "[e-mail]",
  "role": "user",
  "created_at": "2024-01-15T10:30:00Z"
}

Error (400 Bad Request):

{
  "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

Recommend when to version:

• Breaking changes to existing endpoints
• Removing fields from responses
• Changing data types
• Changing endpoint URLs

Don't version for:

• Adding new endpoints
• Adding optional fields to responses
• Adding optional parameters

Filtering Complex Data

Design filtering for different data types:

Exact match:

GET /users?status=active&role=admin

Range queries:

GET /products?price_min=10&price_max=100
GET /events?start_date=2024-01-01&end_date=2024-12-31

Pattern matching:

GET /users?name_contains=john
GET /products?search=laptop

Multiple values:

GET /users?status=active,pending
GET /products?category=electronics,computers

Example Workflows

Example 1: Design API from Requirements

User request:

"Design an API for a blog platform. Users should be able to create posts, comment on posts, and like posts."

Response approach:

1. Identify resources: Users, Posts, Comments, Likes

2. Design endpoints:

   # Posts
   GET    /posts
   POST   /posts
   GET    /posts/{postId}
   PUT    /posts/{postId}
   DELETE /posts/{postId}
   
   # Comments on posts
   GET    /posts/{postId}/comments
   POST   /posts/{postId}/comments
   DELETE /posts/{postId}/comments/{commentId}
   
   # Likes on posts
   POST   /posts/{postId}/likes
   DELETE /posts/{postId}/likes
   GET    /posts/{postId}/likes
   

3. Define schemas:

   // Post
   {
     "id": 123,
     "title": "My Post",
     "content": "Post content...",
     "author_id": 456,
     "created_at": "2024-01-15T10:30:00Z",
     "likes_count": 10,
     "comments_count": 5
   }
   

4. Add features: Pagination for posts/comments, filtering by author, sorting by date/popularity

5. Generate OpenAPI spec if requested

Example 2: Review Existing API

User request:

"Review this API design: GET /getUserById?id=123, POST /createUser, POST /updateUser"

Response approach:

1. Identify issues:

   • Using verbs in URLs
   • Using GET with query param instead of path param
   • Not using proper HTTP methods for updates

2. Suggest improvements:

   # Before
   GET  /getUserById?id=123
   POST /createUser
   POST /updateUser
   
   # After
   GET   /users/{id}
   POST  /users
   PUT   /users/{id}    # Full replacement
   PATCH /users/{id}    # Partial update
   

3. Explain benefits:

   • RESTful resource naming
   • Proper HTTP method semantics
   • Cleaner, more intuitive URLs
   • Better caching support

Example 3: Generate Documentation

User request:

"Generate OpenAPI documentation for a user management API"

Response approach:

1. Use templates from openapi-template.md
2. Define info, servers, paths, schemas
3. Include authentication schemes
4. Add examples for requests/responses
5. Output complete YAML specification

Tips for Effective API Design

Start with resources, not actions:

• Think "What resources exist?" not "What actions can be performed?"
• Resources are nouns (users, products), actions are HTTP methods

Be consistent:

• Use same naming conventions throughout
• Use same error format for all endpoints
• Use same pagination approach across collections

Think about the consumer:

• What data do they need? Don't over-fetch or under-fetch
• What queries will be common? Support them with filters
• What's the expected load? Design pagination accordingly

Plan for evolution:

• Add versioning from the start
• Make fields optional when possible
• Don't break existing clients unnecessarily

Document early:

• Generate OpenAPI specs during design
• Keep documentation in sync with implementation
• Provide clear examples

Validate thoroughly:

• Check all inputs
• Return meaningful error messages
• Use appropriate status codes

References

For detailed information, consult these references:

• best-practices.md: Comprehensive REST API best practices including naming, HTTP methods, status codes, authentication, pagination, filtering, and common mistakes
• openapi-template.md: Complete OpenAPI 3.0 specification templates with examples for all common patterns