pinkpixel-dev/api-documentation-writer

API Documentation Writer

Create comprehensive, developer-friendly API documentation.

Instructions

When a user needs API documentation:

1. Gather API Information:

   • API type (REST, GraphQL, WebSocket, gRPC)?
   • Authentication method (API key, OAuth, JWT)?
   • Base URL and versioning strategy?
   • Available endpoints and their purposes?
   • Request/response formats?
   • Rate limiting or usage restrictions?

2. Generate Complete Documentation Structure:

   Overview Section:

   • What the API does (1-2 sentences)
   • Key capabilities
   • Getting started checklist
   • Support and resources

   Authentication:

   • How to obtain credentials
   • Where to include auth tokens
   • Example authenticated request
   • Token refresh process (if applicable)

   Base URL & Versioning:

   • Production and sandbox URLs
   • Version format (path, header, query param)
   • Current version and changelog link

   Endpoints (for each endpoint):

   • HTTP method and path
   • Description of what it does
   • Path parameters
   • Query parameters
   • Request headers
   • Request body schema
   • Response codes and meanings
   • Response body schema
   • Example request (curl, JavaScript, Python)
   • Example response (formatted JSON)

   Error Handling:

   • Standard error response format
   • Common error codes and meanings
   • Troubleshooting guide

   Rate Limiting:

   • Limits and windows
   • Headers to check
   • How to handle rate limit errors

   SDKs & Libraries:

   • Official client libraries
   • Community libraries
   • Installation instructions

   Webhooks (if applicable):

   • Available webhook events
   • Setup process
   • Payload examples
   • Security verification

3. Format Output (REST API example):

   # [API Name] Documentation
   
   ## Overview
   
   [Brief description of what the API does]
   
   **Base URL**: `https://api.example.com/v1`
   
   **Authentication**: API Key via `Authorization` header
   
   ## Quick Start
   
   1. [Step 1]
   2. [Step 2]
   3. [Step 3]
   
   ## Authentication
   
   All requests require an API key in the `Authorization` header:
   
   

   Authorization: Bearer YOUR_API_KEY

   
   Get your API key from [dashboard link].
   
   ## Endpoints
   
   ### GET /resource
   
   Retrieve a list of resources.
   
   **Parameters**:
   - `limit` (optional, integer): Number of results (max 100, default 10)
   - `offset` (optional, integer): Pagination offset (default 0)
   - `filter` (optional, string): Filter by field
   
   **Request Example**:
   ```bash
   curl -X GET "https://api.example.com/v1/resource?limit=10" \
     -H "Authorization: Bearer YOUR_API_KEY"
   

   Response (200 OK):

   {
     "data": [
       {
         "id": "123",
         "name": "Example",
         "created_at": "2024-01-15T10:00:00Z"
       }
     ],
     "total": 100,
     "limit": 10,
     "offset": 0
   }
   

   Response Codes:

   • 200 - Success
   • 400 - Bad request (invalid parameters)
   • 401 - Unauthorized (invalid API key)
   • 429 - Rate limit exceeded
   • 500 - Server error

   POST /resource

   Create a new resource.

   Request Body:

   {
     "name": "string (required)",
     "description": "string (optional)",
     "metadata": "object (optional)"
   }
   

   Request Example:

   curl -X POST "https://api.example.com/v1/resource" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "My Resource",
       "description": "A test resource"
     }'
   

   Response (201 Created):

   {
     "id": "124",
     "name": "My Resource",
     "description": "A test resource",
     "created_at": "2024-01-15T10:30:00Z"
   }
   

   Error Handling

   All errors follow this format:

   {
     "error": {
       "code": "invalid_request",
       "message": "The 'name' field is required",
       "details": {
         "field": "name"
       }
     }
   }
   

   Common Error Codes:

   • invalid_request - Malformed request
   • authentication_failed - Invalid API key
   • not_found - Resource doesn't exist
   • rate_limit_exceeded - Too many requests
   • internal_error - Server error

   Rate Limiting

   Limits: 1000 requests per hour

   Headers:

   • X-RateLimit-Limit: Total requests allowed
   • X-RateLimit-Remaining: Requests remaining
   • X-RateLimit-Reset: Timestamp when limit resets

   When rate limited, you'll receive a 429 status code.

   Code Examples

   JavaScript (Node.js)

   const response = await fetch('https://api.example.com/v1/resource', {
     headers: {
       'Authorization': 'Bearer YOUR_API_KEY'
     }
   });
   const data = await response.json();
   

   Python

   import requests
   
   response = requests.get(
     'https://api.example.com/v1/resource',
     headers={'Authorization': 'Bearer YOUR_API_KEY'}
   )
   data = response.json()
   

   Support

   • Documentation: https://docs.example.com
   • Support: [email protected]
   • Status: https://status.example.com

4. For GraphQL APIs, adapt to show:

   • Schema definitions
   • Query examples
   • Mutation examples
   • Subscription examples
   • Variables and directives

5. Documentation Best Practices:

   • Start with working example (copy-paste ready)
   • Show both request and response
   • Use realistic example data
   • Include error cases
   • Explain every parameter
   • Provide code examples in multiple languages
   • Use consistent formatting
   • Add "Try it" interactive examples when possible
   • Link related endpoints
   • Include changelog and versioning

6. Developer Experience Tips:

   • Include a "Quick Start" with working example in 60 seconds
   • Provide Postman collection or OpenAPI spec
   • Show common use cases and workflows
   • Include troubleshooting section
   • Add testing/sandbox environment
   • Provide SDKs with installation instructions
   • Include rate limiting details upfront
   • Show pagination patterns
   • Explain filtering and sorting options

Example Triggers

• "Write API documentation for my REST endpoints"
• "Create OpenAPI spec for my API"
• "Document this GraphQL schema"
• "Generate developer docs for my webhook API"
• "Write authentication guide for API"

Output Quality

Ensure documentation:

• Starts with working example
• Explains every parameter and field
• Shows realistic request/response examples
• Includes error handling
• Provides code samples in multiple languages
• Uses consistent formatting
• Is organized logically (most common operations first)
• Includes authentication clearly
• Covers edge cases and limitations
• Follows REST/GraphQL best practices
• Is scannable with good use of headers
• Includes interactive examples when possible

Generate comprehensive, developer-friendly API documentation that makes integration effortless.