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": "john@example.com",
  "role": "user"
}

Response

Success (201 Created):

{
  "id": 123,
  "name": "John Doe",
  "email": "john@example.com",
  "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:

   code

   # 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:

   json

   // 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:

   code

   # 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