APISite Specialization

The APISite type is optimized for API documentation and developer portals. It extends the base Site component with specialized components for API reference documentation, interactive playgrounds, code samples, authentication guides, and changelog management.

Naming Convention

APISite follows the ${SiteType}${Component} pattern:

APIHeader = Header + version selector and API status
APISidebar = Sidebar + API navigation tree
APIReference = Reference + endpoint documentation
APIPlayground = Playground + interactive testing
CodeSamples = Samples + multi-language examples
Authentication = Auth + authentication guides

All API components are the base component enhanced with API site-specific capabilities.

Type Definition

import type { APISite } from 'mdxui'

interface APISite extends BaseSite {
  type: 'api'
  api?: {
    specUrl?: string          // OpenAPI/Swagger spec URL
    playground?: boolean      // Enable API playground (default: true)
    auth?: boolean           // Show auth docs (default: true)
    codeSamples?: boolean    // Include code samples (default: true)
    languages?: string[]     // Code sample languages
  }
}

Usage

Basic Example

import { Site, APIHeader, APISidebar, APIReference } from '@mdxui/beacon'

<Site
  type="api"
  name="Acme API"
  api={{
    specUrl: "/openapi.json",
    playground: true,
    codeSamples: true,
    languages: ["javascript", "python", "curl"]
  }}
>
  <APIHeader />
  <APISidebar />
  <APIReference />
</Site>

With OpenAPI Spec

<Site
  type="api"
  name="REST API v2.0"
  api={{
    specUrl: "https://api.acme.com/openapi.json",
    playground: true,
    auth: true
  }}
>
  {/* Auto-generates docs from OpenAPI spec */}
</Site>

Required Components

APISite requires these specialized components:

APIHeader

Required: Yes

API documentation header with version selector and status.

<APIHeader
  logo={<Logo />}
  versions={[
    { label: "v2.0", value: "v2.0", current: true },
    { label: "v1.9", value: "v1.9" }
  ]}
  status={{
    operational: true,
    url: "/status"
  }}
  navigation={[
    { label: "Docs", href: "/docs" },
    { label: "API Reference", href: "/api" },
    { label: "Guides", href: "/guides" },
    { label: "SDKs", href: "/sdks" }
  ]}
  apiKey={{
    visible: true,
    value: "sk_test_xxx"
  }}
/>

APISidebar

Required: Yes

API navigation sidebar organized by resources.

<APISidebar
  navigation={[
    {
      title: "Getting Started",
      items: [
        { title: "Introduction", href: "/docs" },
        { title: "Authentication", href: "/docs/auth" },
        { title: "Rate Limits", href: "/docs/rate-limits" }
      ]
    },
    {
      title: "API Reference",
      items: [
        {
          title: "Users",
          items: [
            { title: "GET /users", href: "/api/users/list", method: "GET" },
            { title: "POST /users", href: "/api/users/create", method: "POST" }
          ]
        },
        {
          title: "Products",
          items: [
            { title: "GET /products", href: "/api/products/list", method: "GET" }
          ]
        }
      ]
    }
  ]}
  currentPath="/api/users/list"
/>

APIReference

Required: Yes

API endpoint reference documentation.

<APIReference
  endpoint={{
    method: "GET",
    path: "/v1/users",
    description: "List all users",
    authentication: "API Key",
    parameters: [
      {
        name: "limit",
        type: "integer",
        in: "query",
        required: false,
        description: "Number of results to return",
        default: 10
      },
      {
        name: "offset",
        type: "integer",
        in: "query",
        required: false,
        description: "Pagination offset"
      }
    ],
    responses: [
      {
        status: 200,
        description: "Success",
        schema: {
          type: "object",
          properties: {
            data: { type: "array" },
            total: { type: "integer" }
          }
        },
        example: {
          data: [{ id: "1", name: "John" }],
          total: 100
        }
      }
    ],
    errors: [
      { status: 401, description: "Unauthorized" },
      { status: 429, description: "Rate limit exceeded" }
    ]
  }}
/>

Optional Components

APIPlayground

Interactive API testing playground.

<APIPlayground
  endpoint={{
    method: "GET",
    path: "/v1/users",
    baseUrl: "https://api.acme.com"
  }}
  authentication={{
    type: "bearer",
    token: userApiKey
  }}
  parameters={[
    { name: "limit", value: "10" },
    { name: "offset", value: "0" }
  ]}
  onExecute={(request) => {
    // Make API call
    return fetch(request)
  }}
/>

CodeSamples

Multi-language code examples.

<CodeSamples
  endpoint={{
    method: "GET",
    path: "/v1/users",
    parameters: { limit: 10 }
  }}
  languages={[
    {
      language: "javascript",
      label: "JavaScript",
      code: `const response = await fetch('https://api.acme.com/v1/users?limit=10', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})`
    },
    {
      language: "python",
      label: "Python",
      code: `import requests

response = requests.get(
  'https://api.acme.com/v1/users',
  params={'limit': 10},
  headers={'Authorization': 'Bearer YOUR_API_KEY'}
)`
    },
    {
      language: "bash",
      label: "cURL",
      code: `curl -X GET 'https://api.acme.com/v1/users?limit=10' \\
  -H 'Authorization: Bearer YOUR_API_KEY'`
    }
  ]}
  defaultLanguage="javascript"
/>

Authentication

Authentication documentation and guides.

<Authentication
  methods={[
    {
      type: "api-key",
      title: "API Key",
      description: "Pass your API key in the Authorization header",
      example: "Authorization: Bearer sk_live_xxx",
      howToGet: "/dashboard/api-keys"
    },
    {
      type: "oauth",
      title: "OAuth 2.0",
      description: "Use OAuth for user-based authentication",
      flows: ["authorization_code", "client_credentials"],
      scopes: ["read", "write", "admin"]
    }
  ]}
  generateKey={true}
  testConnection={true}
/>

RateLimits

Rate limit information and monitoring.

<RateLimits
  limits={[
    {
      plan: "Free",
      limit: "100 requests/hour",
      burst: 10
    },
    {
      plan: "Pro",
      limit: "10,000 requests/hour",
      burst: 100
    }
  ]}
  currentUsage={{
    used: 45,
    limit: 100,
    reset: "2024-01-15T14:00:00Z"
  }}
  headers={{
    limit: "X-RateLimit-Limit",
    remaining: "X-RateLimit-Remaining",
    reset: "X-RateLimit-Reset"
  }}
/>

Changelog

API changelog with version history.

<Changelog
  versions={[
    {
      version: "v2.0",
      date: "2024-01-15",
      changes: [
        {
          type: "breaking",
          description: "Removed deprecated /v1/legacy endpoint"
        },
        {
          type: "feature",
          description: "Added pagination support to /users endpoint"
        },
        {
          type: "fix",
          description: "Fixed rate limit headers in error responses"
        }
      ]
    },
    {
      version: "v1.9",
      date: "2023-12-01",
      changes: [
        {
          type: "feature",
          description: "Added webhook support"
        }
      ]
    }
  ]}
/>

Component Specializations

APIHeader

Base Header component + API features.

// Enhanced with:
- Version selector dropdown
- API status indicator
- API key visibility toggle
- Environment switcher (production/sandbox)
- Language selector for code samples

APISidebar

Base Sidebar component + API navigation.

// Enhanced with:
- Grouped by resource
- HTTP method badges (GET, POST, etc.)
- Quick search/filter endpoints
- Collapsible sections
- Active endpoint highlighting

APIReference

Endpoint documentation with schema.

// Enhanced with:
- HTTP method and path
- Request/response schemas
- Parameter documentation
- Example requests/responses
- Error codes and descriptions
- Try it out button → Playground

APIPlayground

Interactive API testing.

// Enhanced with:
- Live API requests
- Parameter editing
- Authentication handling
- Response inspection
- Request history
- Copy as cURL/code

OpenAPI Integration

Auto-Generate from OpenAPI

<Site
  type="api"
  api={{
    specUrl: "/openapi.json"
  }}
>
  {/* Automatically generates:
    - API navigation from paths
    - Endpoint documentation
    - Request/response schemas
    - Code samples
  */}
</Site>

OpenAPI Spec Example

openapi: 3.0.0
info:
  title: Acme API
  version: 2.0.0
paths:
  /users:
    get:
      summary: List users
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array

Code Generation

SDK Code Samples

Automatically generate code samples:

<CodeSamples
  endpoint={endpoint}
  languages={["javascript", "python", "ruby", "go", "php"]}
  includeSDK={true}
  sdkVersions={{
    javascript: "@acme/sdk@2.0.0",
    python: "acme-sdk==2.0.0"
  }}
/>

cURL Examples

<CurlExample
  method="POST"
  url="https://api.acme.com/v1/users"
  headers={{
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
  }}
  body={{
    name: "John Doe",
    email: "john@example.com"
  }}
/>

Schema Documentation

Request Schema

<RequestSchema
  contentType="application/json"
  schema={{
    type: "object",
    required: ["name", "email"],
    properties: {
      name: {
        type: "string",
        description: "User's full name"
      },
      email: {
        type: "string",
        format: "email",
        description: "User's email address"
      }
    }
  }}
  example={{
    name: "John Doe",
    email: "john@example.com"
  }}
/>

Response Schema

<ResponseSchema
  status={200}
  description="Success"
  schema={{
    type: "object",
    properties: {
      id: { type: "string" },
      name: { type: "string" },
      email: { type: "string" },
      createdAt: { type: "string", format: "date-time" }
    }
  }}
  example={{
    id: "usr_123",
    name: "John Doe",
    email: "john@example.com",
    createdAt: "2024-01-15T10:00:00Z"
  }}
/>

Best Practices

API Documentation

Clear descriptions: Explain what each endpoint does
Complete examples: Show real request/response data
All parameters: Document every parameter and header
Error codes: List all possible error responses
Rate limits: Explain limits and best practices
Changelog: Document all breaking changes

Developer Experience

Interactive playground: Let developers try APIs
Code samples: Multiple languages
Quick start: Get developers running fast
SDKs: Provide official client libraries
Webhooks: Document event-driven integrations
Support: Clear support channels

API Design

Versioning: Clear version strategy
Consistency: Uniform naming and patterns
REST principles: Standard HTTP methods
Pagination: Consistent pagination
Filtering: Standard query parameters
Errors: Consistent error format

Real-World Example

Complete API documentation site:

import {
  Site,
  APIHeader,
  APISidebar,
  APIReference,
  APIPlayground,
  CodeSamples,
  Authentication,
  RateLimits,
  Changelog
} from '@mdxui/beacon'

<Site
  type="api"
  name="Acme API Documentation"
  domain="api.acme.com"
  api={{
    specUrl: "https://api.acme.com/openapi.json",
    playground: true,
    auth: true,
    codeSamples: true,
    languages: ["javascript", "python", "ruby", "go", "curl"]
  }}
>
  <APIHeader
    logo={<Logo />}
    versions={apiVersions}
    status={apiStatus}
    apiKey={userApiKey}
  />

  <div className="api-docs-layout">
    <APISidebar
      navigation={apiNavigation}
      currentPath={currentEndpoint}
    />

    <main>
      {/* Getting Started */}
      <section>
        <h1>Getting Started</h1>

        <Authentication
          methods={authMethods}
          generateKey={true}
          testConnection={true}
        />

        <RateLimits
          limits={rateLimits}
          currentUsage={currentUsage}
        />
      </section>

      {/* API Reference */}
      <APIReference
        endpoint={{
          method: "GET",
          path: "/v1/users",
          description: "Retrieve a list of users",
          authentication: "API Key",
          parameters: endpointParams,
          responses: endpointResponses,
          errors: endpointErrors
        }}
      />

      {/* Code Samples */}
      <CodeSamples
        endpoint={currentEndpoint}
        languages={supportedLanguages}
        defaultLanguage="javascript"
      />

      {/* Interactive Playground */}
      <APIPlayground
        endpoint={currentEndpoint}
        authentication={authConfig}
        onExecute={handleApiRequest}
      />

      {/* Request/Response Examples */}
      <section>
        <h3>Request</h3>
        <RequestSchema
          schema={requestSchema}
          example={requestExample}
        />

        <h3>Response</h3>
        <ResponseSchema
          status={200}
          schema={responseSchema}
          example={responseExample}
        />
      </section>

      {/* Error Codes */}
      <ErrorCodes
        errors={[
          { code: 400, name: "Bad Request", description: "Invalid parameters" },
          { code: 401, name: "Unauthorized", description: "Invalid API key" },
          { code: 429, name: "Too Many Requests", description: "Rate limit exceeded" }
        ]}
      />
    </main>

    {/* Table of Contents */}
    <aside>
      <TableOfContents
        sections={[
          { id: "authentication", title: "Authentication" },
          { id: "parameters", title: "Parameters" },
          { id: "responses", title: "Responses" },
          { id: "examples", title: "Examples" },
          { id: "errors", title: "Error Codes" }
        ]}
      />
    </aside>
  </div>

  {/* Changelog */}
  <Changelog
    versions={apiVersionHistory}
  />
</Site>

TypeScript

Full type definition:

import { z } from 'zod'
import { BaseSiteSchema } from 'mdxui/zod'

export const APISiteSchema = BaseSiteSchema.extend({
  type: z.literal('api'),
  api: z.object({
    specUrl: z.string().optional(),
    playground: z.boolean().default(true),
    auth: z.boolean().default(true),
    codeSamples: z.boolean().default(true),
    languages: z.array(z.string()).optional(),
  }).optional(),
})

export type APISite = z.infer<typeof APISiteSchema>

Site Component - Base site configuration
DocsPage Component - Documentation pages
CodeBlock Component - Syntax highlighting
API Widgets - API-specific components

APISite Specialization

On this page