Skip to main content

​
Understanding the ButterCMS API architecture

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.

​
Request flow

Read operations query cached content from edge locations, while write operations process through the primary API and trigger cache invalidation.

​
Performance topics

Query Optimization

How to use exclude_body, levels, and ordering to minimize response size and serialization overhead

Pagination

How to use page-based and offset-based pagination, infinite scroll, and archive page patterns

Filtering Requests

How to filter by author, category, tag, and custom field values server-side

Caching Strategies

Learn how to implement application-level caching for SSG, SSR, and SPA integrations

CDN & Global Delivery

Learn how ButterCMS serves content from 150+ edge locations worldwide

Scaling for High Traffic

Learn how to implement circuit breakers, graceful degradation, and traffic spike strategies

Monitoring API Usage

Learn how to track read/write API consumption and identify optimization opportunities

Rate Limits & Throttling

Learn how to handle rate-limited responses and avoid hitting API throttle limits

​
Performance checklist

  • Use exclude_body=true for all listing endpoints
  • Set appropriate levels parameter (default to 1-2)
  • Implement pagination with 10-25 items per page
  • Add application-level caching for frequently accessed content
  • Set up error handling with retry logic
  • Configure webhooks for cache invalidation
  • Monitor API response times in your application
  • Track API usage in the ButterCMS Analytics dashboard (see Monitoring API Usage)
  • Review and optimize queries that exceed 500ms
  • Consider pre-fetching content for predictable navigation