API Blocks - Interactive API Documentation

API blocks allow you to create rich, interactive API endpoint documentation directly in your documents. These blocks provide a professional way to document REST APIs with automatic code generation, syntax highlighting, and a clean, organized interface.

What are API Blocks?

API blocks are special documentation components that let you:

• 📋 Document API endpoints with complete details
• 🔧 Define request parameters, headers, and body content
• 📊 Show multiple response examples with different status codes
• 💻 Generate code examples in multiple programming languages (cURL, JavaScript, Python, PHP, Go)
• 🎨 Display everything in a beautiful, organized interface

Creating API Blocks

In the Visual Editor

1. Using the Toolbar: Click the "+" button and select "API Documentation" from the tools menu
2. Using Slash Commands: Type /api in any empty line and press Enter
3. Using Shortcuts: Press Ctrl/Cmd + Shift + A to insert an API block

Configuring API Blocks

Basic Information

• Title: A descriptive name for your API endpoint
• Description: Optional detailed explanation of what the endpoint does
• HTTP Method: GET, POST, PUT, DELETE, PATCH, HEAD, or OPTIONS
• Base URL: The root URL of your API (e.g., https://api.example.com)
• Endpoint: The specific path (e.g., /v1/users/{id})

Parameters

Headers

Document required and optional HTTP headers:

"headers": [
    {
        "key": "Authorization",
        "value": "Bearer token for authentication",
        "required": true
    },
    {
        "key": "Content-Type", 
        "value": "application/json",
        "required": false
    }
]

Path Parameters

For dynamic URL segments (like {id} in /users/{id}):

"pathParams": [
    {
        "key": "id",
        "value": "Unique identifier for the user",
        "required": true
    }
]

Query Parameters

For URL query strings:

"queryParams": [
    {
        "key": "include",
        "value": "Comma-separated list of relations to include",
        "required": false
    },
    {
        "key": "limit",
        "value": "Maximum number of results to return",
        "required": false
    }
]

Request Body

Choose from four body types:

JSON Body

"bodyType": "json",
"requestBody": "{\"name\": \"John Doe\", \"email\": \"[email protected]\"}"

Form Data

"bodyType": "form",
"formData": [
    {
        "key": "name",
        "value": "User's full name",
        "required": true
    },
    {
        "key": "avatar",
        "value": "Profile image file",
        "required": false
    }
]

Raw Text

"bodyType": "raw",
"rawBody": "Plain text or any other format"

No Body

"bodyType": "none"

Response Examples

Document different response scenarios:

"responses": {
    "200": {
        "description": "User created successfully",
        "body": "{\"id\": 123, \"name\": \"John Doe\", \"email\": \"[email protected]\"}"
    },
    "400": {
        "description": "Invalid request data",
        "body": "{\"error\": \"Validation failed\", \"details\": [\"Email is required\"]}"
    },
    "401": {
        "description": "Authentication required",
        "body": "{\"error\": \"Unauthorized\", \"message\": \"Please provide a valid API key\"}"
    },
    "404": {
        "description": "User not found",
        "body": "{\"error\": \"Not found\", \"message\": \"User with ID 123 does not exist\"}"
    }
}

Working with API Blocks

Visual Editor Interface

The API block editor has two main modes:

Preview Mode

Shows the final rendered output with:

• HTTP method badge and full URL
• Organized parameter sections
• Response examples with syntax highlighting
• Code generation in multiple languages
• Copy-to-clipboard functionality

Configuration Mode

Provides form inputs for:

• Basic endpoint information
• Parameter management (add, edit, remove)
• Request body configuration
• Response examples editor with JSON validation

Code Generation

API blocks automatically generate code examples in:

• cURL: Command-line HTTP requests
• JavaScript: Using fetch API
• Python: Using requests library
• PHP: Using cURL or Guzzle
• Go: Using net/http package

Each example includes:

• Proper authentication headers
• All specified parameters
• Correctly formatted request body
• Error handling (where applicable)

Copy Functionality

Every code example includes a copy button for easy integration into your development workflow.

Best Practices

Documentation Structure

1. Use Clear Titles: Make endpoint purposes immediately clear1. ✅ "Create User Account"
2. ❌ "POST /users"
3. Write Helpful Descriptions: Explain the endpoint's purpose and behavior

   "description": "Creates a new user account with email verification. Returns the created user data and sends a welcome email."

1. Include Realistic Examples: Use actual data that developers might encounter

   "requestBody": "{\"name\": \"Alice Johnson\", \"email\": \"[email protected]\", \"role\": \"developer\"}"

Parameter Documentation

1. Be Descriptive: Use the value field to explain what each parameter does

   {
       "key": "limit",
       "value": "Maximum number of items to return (1-100, default: 20)",
       "required": false
   }

1. Mark Required Fields: Always specify if a parameter is required
2. Show Expected Formats: Include format examples in descriptions

   {
       "key": "created_after",
       "value": "ISO 8601 date string (e.g., 2023-01-01T00:00:00Z)",
       "required": false
   }

Response Examples

1. Cover Common Scenarios: Document success and common error cases
2. Use Realistic Data: Show actual response structures
3. Include Error Details: Show how your API communicates errors
4. Status Code Accuracy: Use appropriate HTTP status codes

Endpoint Organization

1. Group Related Endpoints: Document related functionality together
2. Consistent Naming: Use consistent patterns across your API
3. Version Information: Include API version in base URLs when applicable

AI-Generated API Blocks

When using DocuWriter.ai's AI generators to create documentation from code, the system automatically detects API routes and controllers and generates appropriate API blocks. The AI will:

• Extract endpoint information from route definitions
• Infer parameter types from controller methods
• Generate realistic request/response examples
• Include proper authentication headers based on middleware

To get better AI-generated API blocks:

1. Use Clear Route Names: Well-named routes help the AI understand purpose
2. Add Comments: Controller comments help generate better descriptions
3. Use Type Hints: PHP type hints help infer parameter types
4. Include Validation: Laravel form requests help document required fields

Troubleshooting

Common Issues

API Block Doesn't Appear

• Check that your JSON syntax is valid
• Ensure the code block uses api as the language
• Verify all required fields (title, method, baseUrl, endpoint) are present

Code Examples Missing

• Check that the endpoint URL is complete and valid
• Ensure parameters are properly formatted
• Verify the HTTP method is specified correctly

Formatting Issues

• Use proper JSON formatting with escaped quotes inside strings
• Check that all objects and arrays are properly closed
• Validate JSON syntax using the visual editor's validation

Monaco Editor Problems

• If the JSON editor doesn't load, check browser console for errors
• Clear browser cache if syntax highlighting isn't working
• Ensure JavaScript is enabled

Getting Help

If you encounter issues with API blocks:

1. Check the browser console for JavaScript errors
2. Verify your JSON syntax using an online validator
3. Try recreating the block using the visual editor
4. Contact support with specific error messages