> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API architecture & principles

> ButterCMS API architecture and performance characteristics for developers integrating headless CMS functionality.

## Core design principles

ButterCMS provides a REST API that serves content through a globally distributed infrastructure. Content created through the dashboard or Write API is immediately available via read endpoints with automatic global distribution for optimized delivery.

### RESTful design

The ButterCMS API follows REST (Representational State Transfer) architecture, which means:

* **Resource-Oriented URLs**: Each URL represents a specific resource (pages, collections, posts)
* **HTTP Methods**: Standard HTTP verbs indicate the action (GET for reading, POST for creating, PUT/PATCH for updating, DELETE for removing)
* **Stateless Requests**: Each request contains all information needed to process it
* **JSON Responses**: All responses use JSON format for consistency and ease of parsing

### Base URL

All API requests are made to:

```
https://api.buttercms.com/v2
```

## Architecture overview

```mermaid theme={null}
flowchart TB
    Pages["Pages<br/><small>• Single Pages<br/>• Page Types</small>"]
    Collections["Collections<br/><small>• Categories<br/>• Products<br/>• Team Members</small>"]
    Blog["Blog Posts<br/><small>• Authors<br/>• Categories<br/>• Tags</small>"]

    Pages <-->|" "| Collections

    Refs["Reference Fields (slugs/IDs)<br/><small>One-to-One or One-to-Many</small>"]
    Pages --> Refs
    Collections --> Refs
```

## Content types

The API supports creating, updating, and deleting items of three main content types:

### Pages

Fully customizable, reusable schemas that are supercharged with features like structured local and global components, form integrations, and repeaters. These can be individually fetched via a slug and are ideal for complex web content requiring flexible layouts and advanced functionality.

### Collections

Lighter-weight, customizable, reusable schemas for tables of data that are fetched via ID. Perfect for structured content like categories, team members, or product catalogs that primarily serve as reference data. Collections are optimized for simpler data structures and faster querying, making them ideal for content that needs to be referenced by Pages or queried directly from the API.

### Blog Posts

Built-in content type from our blog engine, which comes out-of-the-box with categorization, tagging, predefined SEO, and authors. Designed for chronological content with standardized blog functionality and includes features like automated RSS feeds and WordPress import capabilities.

## Global CDN infrastructure

Content delivery operates through a global CDN with 150+ edge locations. Read operations are cached for 20 days at edge locations by default, providing sub-100ms response times for cached content worldwide.

### Request flow

```mermaid theme={null}
flowchart LR
    Client["Client<br/>Application"]
    CDN["Global CDN<br/><small>(150+ edges)</small>"]
    API["ButterCMS<br/>API"]
    BG["Background<br/>Processing<br/><small>Media Upload<br/>Validation<br/>Webhooks<br/>Cache Refresh</small>"]

    Client --> CDN
    CDN --> API
    API --> BG

    CDN -->|Cache Hit<br/>50-100ms| Cached["Cached<br/>Response"]

    API -.-|Cache Miss<br/>200-500ms| CDN
```

### Cache behavior

* **Initial requests** fetch content from the API and populate edge caches (\~200-500ms)
* **Subsequent requests** serve from the nearest location (\~50-100ms)
* **Content updates** automatically invalidate relevant cache entries globally, including all content that references the changed content

## Publication states

Content can exist in three states:

| State         | Description                             | Access                          |
| ------------- | --------------------------------------- | ------------------------------- |
| **Draft**     | Content being edited, not yet live      | Preview mode only (`preview=1`) |
| **Published** | Live content accessible via API         | Standard API endpoints          |
| **Scheduled** | Automatic publication at specified time | Preview until publication time  |

State changes trigger system-wide operations including cache invalidation, webhook notifications, and reference resolution across related content.

## Write operations

Create and update operations return `202 Accepted` for immediate feedback while background processing handles tasks like media uploads, validation, and webhook notifications. This ensures consistent fast response times regardless of operation complexity.

## Integration patterns

For easiest implementation, ButterCMS API integration should follow a structured approach of these sequential steps: content architecture planning, API endpoint integration, performance optimization, and production deployment. Content must be designed in your ButterCMS dashboard first to establish schema and reference relationships before implementing API calls in your application.

### Static site generation (SSG)

Implementations fetch content during build processes and utilize webhook-triggered rebuilds for content updates. This pattern provides maximum performance through pre-built pages and CDN distribution but requires build system integration for content synchronization. Build-time fetching typically uses batch API calls to retrieve all necessary content, implementing error handling for API availability during build processes.

```mermaid theme={null}
flowchart LR
    subgraph SSG["SSG (Build Time)"]
        direction LR
        Content --> Build["Build Process"]
        Build --> Static["Static Files"]
        Static --> CDN1["CDN"]
        CDN1 --> Users
        Webhook["Webhook"] -.->|triggers rebuild| Build
    end
```

### Server-side rendering (SSR)

Applications fetch content on each request, implementing application-level caching to optimize performance while maintaining real-time content updates. Request-time fetching allows for personalized content and immediate content updates but requires careful cache management and error handling for API unavailability scenarios.

```mermaid theme={null}
flowchart LR
    subgraph SSR["SSR (Request Time)"]
        direction LR
        Request["User Request"] --> Server
        Server --> API["API Call"]
        API --> Page["Dynamic Page"]
        Page --> User
        Server -.-> Cache["App-level cache"]
    end
```

### Single page applications (SPA)

Client-side content fetching with progressive loading patterns, utilizing browser caching and API response caching for optimal user experience. Client-side integration enables dynamic content updates and interactive experiences but requires consideration of API key security and CORS configuration.

```mermaid theme={null}
flowchart LR
    subgraph SPA["SPA (Client Side)"]
        direction LR
        User2["User"] --> Shell["App Shell"]
        Shell --> APIs["API Calls"]
        APIs --> Updates["Dynamic Updates"]
        Updates --> UI
        Shell -.-> BCache["Browser cache"]
    end
```

## API efficiency

Strategic parameter usage improves performance significantly:

* **`exclude_body=true`**: Reduces response size by 50-70% for content listing operations
* **`levels` parameter**: Controls reference depth (1-5, default 2) to balance data completeness with response time
* **Pagination**: Use appropriate page sizes for large content sets, typically 10-25 items per request for optimal performance

## Error handling

Implement graceful degradation patterns for API unavailability, retry logic with exponential backoff for transient failures, and fallback content mechanisms for critical application functionality. Applications should monitor API response times and implement circuit breaker patterns for sustained API issues. Content architecture should minimize reference depth requirements and design reference patterns to avoid circular dependencies that impact API performance.

## Key features summary

| Feature               | Description                                 |
| --------------------- | ------------------------------------------- |
| **REST Architecture** | Predictable, resource-oriented URLs         |
| **JSON Responses**    | All responses in JSON format                |
| **Global CDN**        | 150+ edge locations worldwide               |
| **Fast Responses**    | Sub-100ms for cached content                |
| **Automatic Caching** | 20-day edge cache with smart invalidation   |
| **Webhooks**          | Real-time notifications for content changes |
| **Localization**      | Multi-language content support              |

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="../concepts/authentication-api-tokens">
    Learn how to authenticate your API requests
  </Card>

  <Card title="REST Endpoints" icon="route" href="../concepts/rest-endpoints-urls">
    Explore all available API endpoints
  </Card>

  <Card title="Request/Response Format" icon="code" href="../concepts/request-response-format">
    Understand the JSON data structure
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="../concepts/http-status-codes-errors">
    Handle errors gracefully
  </Card>
</CardGroup>