@lsendel/claude-agents/standards/api-design.md

Supercharge Claude Code with specialized AI sub-agents for code review, testing, debugging, documentation & more. Now with process & standards management! Easy CLI tool to install, manage & create custom AI agents for enhanced development workflow

---
name: api-design
type: standard
version: 1.0.0
description: LLM-optimized RESTful API design patterns with OpenAPI specifications and best practices
author: Claude
tags: [api, rest, design, standards, openapi, llm-guide]
related_commands: [/design-api, /api-review, /generate-openapi]
---

# API Design Standards for LLMs

> Version: 1.0.0
> Last updated: 2025-07-29
> Purpose: Enable LLMs to design and review REST APIs consistently
> Target: Language models creating or reviewing API specifications

## Context for LLM Usage

This guide is specifically designed for language models designing REST APIs. When creating APIs:
- You will receive requirements in various formats (user stories, technical specs, existing code)
- You should generate OpenAPI specifications following these patterns
- Your output should include examples, error cases, and integration documentation
- You must consider security, performance, and maintainability from the start

## Reading API Requirements

When analyzing API requirements:
1. **Identify Resources**: Extract nouns that represent entities
2. **Map Operations**: Determine CRUD operations needed
3. **Define Relationships**: Understand resource hierarchies
4. **Extract Constraints**: Note rate limits, auth requirements, validation rules

## Core Principles
- Use consistent naming conventions (lowercase, hyphens for word separation)
- Keep endpoints focused and RESTful (one resource per endpoint)
- Standardize response formats (consistent envelope structure)
- Version breaking changes (use /v1, /v2 prefixes)
- Design for pagination from the start
- Include filtering and sorting capabilities
- Plan for future expansion with extensible schemas

## URL Structure

### General Format
```
https://api.example.com/v1/resources/{id}/sub-resources
```

### Rules
- Use lowercase letters
- Separate words with hyphens
- Use plural nouns for collections
- Avoid verbs in URLs (use HTTP methods)

### Examples
```
GET    /api/v1/users              # List users
POST   /api/v1/users              # Create user
GET    /api/v1/users/123          # Get specific user
PUT    /api/v1/users/123          # Update user
DELETE /api/v1/users/123          # Delete user
GET    /api/v1/users/123/orders   # Get user's orders
```

## HTTP Methods
- **GET**: Retrieve resources (safe, idempotent)
- **POST**: Create new resources
- **PUT**: Update entire resource (idempotent)
- **PATCH**: Partial update (idempotent)
- **DELETE**: Remove resources (idempotent)

## Request Standards

### Headers
```http
Content-Type: application/json
Accept: application/json
Authorization: Bearer {token}
X-Request-ID: {unique-id}
```

### Request Body
```json
{
  "data": {
    "type": "user",
    "attributes": {
      "email": "user@example.com",
      "name": "John Doe"
    }
  }
}
```

## Response Standards

### Success Response
```json
{
  "data": {
    "id": "123",
    "type": "user",
    "attributes": {
      "email": "user@example.com",
      "name": "John Doe",
      "createdAt": "2024-01-15T10:30:00Z"
    },
    "links": {
      "self": "/api/v1/users/123"
    }
  },
  "meta": {
    "timestamp": "2024-01-15T10:30:00Z"
  }
}
```

### Collection Response
```json
{
  "data": [
    {
      "id": "123",
      "type": "user",
      "attributes": { ... }
    }
  ],
  "meta": {
    "total": 150,
    "page": 1,
    "perPage": 20
  },
  "links": {
    "self": "/api/v1/users?page=1",
    "next": "/api/v1/users?page=2",
    "last": "/api/v1/users?page=8"
  }
}
```

## Status Codes

### Success Codes
- **200 OK**: Successful GET, PUT, PATCH
- **201 Created**: Successful POST
- **204 No Content**: Successful DELETE
- **202 Accepted**: Request accepted for async processing

### Client Error Codes
- **400 Bad Request**: Invalid request format
- **401 Unauthorized**: Missing or invalid authentication
- **403 Forbidden**: Authenticated but not authorized
- **404 Not Found**: Resource doesn't exist
- **409 Conflict**: Request conflicts with current state
- **422 Unprocessable Entity**: Validation errors

### Server Error Codes
- **500 Internal Server Error**: Generic server error
- **502 Bad Gateway**: Invalid response from upstream
- **503 Service Unavailable**: Service temporarily down
- **504 Gateway Timeout**: Upstream timeout

## Error Handling

### Error Response Format
```json
{
  "errors": [
    {
      "id": "unique-error-id",
      "status": "422",
      "code": "VALIDATION_ERROR",
      "title": "Validation Failed",
      "detail": "Email format is invalid",
      "source": {
        "pointer": "/data/attributes/email"
      },
      "meta": {
        "timestamp": "2024-01-15T10:30:00Z"
      }
    }
  ]
}
```

### Error Codes
- Use consistent, descriptive error codes
- Include both HTTP status and application-specific codes
- Provide actionable error messages

## Pagination

### Query Parameters
```
GET /api/v1/users?page=2&per_page=20
GET /api/v1/users?offset=20&limit=20
GET /api/v1/users?cursor=eyJpZCI6MTIzfQ
```

### Pagination Headers
```http
X-Total-Count: 150
X-Page: 2
X-Per-Page: 20
Link: <...?page=3>; rel="next", <...?page=1>; rel="prev"
```

## Filtering and Sorting

### Filtering
```
GET /api/v1/users?filter[status]=active
GET /api/v1/users?filter[created_at][gte]=2024-01-01
GET /api/v1/users?q=john
```

### Sorting
```
GET /api/v1/users?sort=created_at
GET /api/v1/users?sort=-created_at,name
```

## Versioning

### URL Versioning (Recommended)
```
https://api.example.com/v1/users
https://api.example.com/v2/users
```

### Header Versioning
```http
Accept: application/vnd.api+json;version=1
API-Version: 1
```

### Version Deprecation
- Announce deprecation well in advance
- Include deprecation warnings in responses
- Provide migration guides
- Support old versions for reasonable time

## Authentication

### Bearer Token
```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
```

### API Key
```http
X-API-Key: your-api-key-here
```

### OAuth 2.0
- Use for third-party integrations
- Implement proper scopes
- Regular token rotation

## Rate Limiting

### Headers
```http
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200
```

### Rate Limit Response
```json
{
  "errors": [{
    "status": "429",
    "code": "RATE_LIMIT_EXCEEDED",
    "title": "Too Many Requests",
    "detail": "Rate limit exceeded. Try again in 60 seconds."
  }]
}
```

## Caching

### Cache Headers
```http
Cache-Control: public, max-age=3600
ETag: "33a64df551425fcc55e4d42a148795d9f25f89d4"
Last-Modified: Wed, 21 Oct 2023 07:28:00 GMT
```

### Conditional Requests
```http
If-None-Match: "33a64df551425fcc55e4d42a148795d9f25f89d4"
If-Modified-Since: Wed, 21 Oct 2023 07:28:00 GMT
```

## Best Practices
- Always use HTTPS
- Don't break existing endpoints
- Implement pagination for collections
- Validate all inputs
- Use parameterized queries
- Implement rate limiting
- Cache appropriately

## Implementation Checklist
- [ ] Consistent URL structure
- [ ] Proper HTTP method usage
- [ ] Standardized responses
- [ ] Error format consistency
- [ ] Pagination for collections
- [ ] Authentication implemented
- [ ] Rate limiting configured
- [ ] API versioning strategy