Headless API Designer

Specialist agent for designing content delivery APIs, GraphQL schemas, and headless CMS integration patterns.

Purpose

Design comprehensive headless CMS APIs including:

• REST API resource design
• GraphQL schema architecture
• Authentication and authorization
• Caching and performance strategies
• SDK and client generation

Design Approach

API Architecture Patterns

┌─────────────────────────────────────────────────────────────────────────┐
│                       HEADLESS API ARCHITECTURE                          │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐              │
│  │   REST API   │    │  GraphQL     │    │  Preview     │              │
│  │  (Standard)  │    │  (Flexible)  │    │  (Draft)     │              │
│  └──────────────┘    └──────────────┘    └──────────────┘              │
│          │                  │                   │                        │
│          └──────────────────┼───────────────────┘                        │
│                             ▼                                            │
│                    ┌──────────────┐                                      │
│                    │    CDN       │                                      │
│                    │  (Caching)   │                                      │
│                    └──────────────┘                                      │
│                             │                                            │
│                             ▼                                            │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │                     CONTENT DELIVERY LAYER                        │  │
│  │  ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐  │  │
│  │  │ Content    │  │ Navigation │  │   Media    │  │   Theme    │  │  │
│  │  │ Resolver   │  │ Builder    │  │ Resolver   │  │ Provider   │  │  │
│  │  └────────────┘  └────────────┘  └────────────┘  └────────────┘  │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Deliverables

1. REST API Design

rest_api:
  base_url: "/api/v1"
  format: JSON-API

  resources:
    # Content
    - name: Content Items
      path: /content
      methods:
        - GET: List content items (paginated, filterable)
        - GET /{id}: Get content item by ID
        - GET /slug/{slug}: Get content item by slug

    - name: Content Types
      path: /content-types
      methods:
        - GET: List available content types
        - GET /{slug}: Get content type schema

    # Pages
    - name: Pages
      path: /pages
      methods:
        - GET: List pages (sitemap)
        - GET /{path}: Get page by URL path
        - GET /{id}/preview: Get page preview (requires auth)

    # Navigation
    - name: Navigation
      path: /navigation
      methods:
        - GET /{menu}: Get menu by identifier
        - GET /breadcrumbs/{path}: Get breadcrumbs for path

    # Media
    - name: Media
      path: /media
      methods:
        - GET /{id}: Get media item metadata
        - GET /{id}/url: Get media URL (with transforms)

    # Taxonomy
    - name: Taxonomy
      path: /taxonomies
      methods:
        - GET: List taxonomies
        - GET /{slug}/terms: Get terms for taxonomy

  query_parameters:
    pagination:
      - page[number]: Page number (default: 1)
      - page[size]: Items per page (default: 20, max: 100)

    filtering:
      - filter[type]: Content type filter
      - filter[status]: Publication status (published|draft)
      - filter[taxonomy.{name}]: Taxonomy term filter
      - filter[field.{name}]: Custom field filter

    include:
      - include: Related resources (comma-separated)

    sorting:
      - sort: Field to sort by (+asc, -desc)

    localization:
      - locale: Content locale (e.g., en-US, fr-FR)

  response_format:
    content_item:
      id: string
      type: string
      attributes:
        title: string
        slug: string
        publishedAt: datetime
        locale: string
        fields: object
      relationships:
        author: { data: { type: user, id: string } }
        taxonomy: { data: [{ type: term, id: string }] }
      links:
        self: string
      meta:
        createdAt: datetime
        updatedAt: datetime

2. GraphQL Schema Design

# Content Types
interface Content {
  id: ID!
  contentType: String!
  title: String!
  slug: String!
  status: ContentStatus!
  publishedAt: DateTime
  locale: String!
  createdAt: DateTime!
  updatedAt: DateTime!
  author: User
}

type Article implements Content {
  id: ID!
  contentType: String!
  title: String!
  slug: String!
  status: ContentStatus!
  publishedAt: DateTime
  locale: String!
  createdAt: DateTime!
  updatedAt: DateTime!
  author: User

  # Article-specific fields
  body: RichText!
  excerpt: String
  featuredImage: Media
  categories: [Term!]!
  tags: [Term!]!
  relatedArticles: [Article!]!
}

type Page implements Content {
  id: ID!
  contentType: String!
  title: String!
  slug: String!
  status: ContentStatus!
  publishedAt: DateTime
  locale: String!
  createdAt: DateTime!
  updatedAt: DateTime!
  author: User

  # Page-specific fields
  path: String!
  template: String!
  zones: [Zone!]!
  seo: SeoMeta
  parent: Page
  children: [Page!]!
}

# Page Builder Types
type Zone {
  name: String!
  widgets: [Widget!]!
}

union Widget = RichTextWidget | ImageWidget | CardGridWidget | CallToActionWidget

type RichTextWidget {
  id: ID!
  type: String!
  content: RichText!
}

type CardGridWidget {
  id: ID!
  type: String!
  columns: Int!
  cards: [Card!]!
}

# Media Types
type Media {
  id: ID!
  filename: String!
  mimeType: String!
  url(width: Int, height: Int, format: ImageFormat): String!
  alt: String
  width: Int
  height: Int
  metadata: MediaMetadata
}

# Navigation
type Menu {
  id: ID!
  name: String!
  items: [MenuItem!]!
}

type MenuItem {
  id: ID!
  label: String!
  url: String
  page: Page
  children: [MenuItem!]!
}

# Queries
type Query {
  # Content queries
  content(id: ID!): Content
  contentBySlug(type: String!, slug: String!, locale: String): Content
  contentList(
    type: String
    locale: String
    status: ContentStatus
    filter: ContentFilter
    first: Int
    after: String
  ): ContentConnection!

  # Page queries
  page(id: ID!): Page
  pageByPath(path: String!, locale: String): Page
  sitemap(locale: String): [SitemapEntry!]!

  # Navigation queries
  menu(name: String!, locale: String): Menu
  breadcrumbs(path: String!): [BreadcrumbItem!]!

  # Media queries
  media(id: ID!): Media

  # Taxonomy queries
  taxonomy(slug: String!): Taxonomy
  terms(taxonomySlug: String!, parentId: ID): [Term!]!

  # Search
  search(query: String!, types: [String!], locale: String, first: Int): SearchResultConnection!
}

# Pagination (Relay-style)
type ContentConnection {
  edges: [ContentEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ContentEdge {
  node: Content!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

3. Authentication & Authorization

authentication:
  # Public API (published content)
  public:
    type: API Key
    header: X-API-Key
    rate_limit: 1000/hour

  # Preview API (draft content)
  preview:
    type: Bearer Token (JWT)
    header: Authorization
    scopes:
      - content:preview
      - media:read
    expiry: 1h

  # Management API (CRUD)
  management:
    type: OAuth 2.0
    grant_types:
      - client_credentials
      - authorization_code
    scopes:
      - content:read
      - content:write
      - media:read
      - media:write
      - settings:read
      - settings:write

authorization:
  # Content-level permissions
  content:
    - rule: Published content accessible to all with API key
    - rule: Draft content requires preview token
    - rule: Unpublished content requires management scope

  # Tenant isolation
  multi_tenant:
    - rule: API key scoped to tenant
    - rule: Content filtered by tenant automatically
    - rule: Cross-tenant access prohibited

4. Caching Strategy

caching:
  # CDN caching
  cdn:
    provider: cloudflare # or cloudfront, azure-front-door
    default_ttl: 3600 # 1 hour
    rules:
      - pattern: /api/v1/content/*
        ttl: 3600
        vary_by: [Accept-Language, X-API-Key]

      - pattern: /api/v1/navigation/*
        ttl: 86400 # 24 hours

      - pattern: /api/v1/media/*
        ttl: 31536000 # 1 year (immutable)

      - pattern: /graphql
        ttl: 0 # No CDN caching for GraphQL
        edge_compute: true # Use edge functions for caching

  # Application-level caching
  application:
    provider: redis
    patterns:
      - key: "content:{id}:{locale}"
        ttl: 900 # 15 min
        invalidation: on_publish

      - key: "navigation:{menu}:{locale}"
        ttl: 3600
        invalidation: on_menu_update

      - key: "sitemap:{locale}"
        ttl: 3600
        invalidation: on_page_change

  # Cache invalidation
  invalidation:
    strategies:
      - event: content.published
        action: purge content cache + related pages

      - event: navigation.updated
        action: purge navigation cache

      - event: media.updated
        action: purge media cache + CDN

    webhooks:
      - url: /webhooks/cache-purge
        events: [content.*, navigation.*, media.*]

5. SDK Generation Spec

sdk_generation:
  # TypeScript SDK
  typescript:
    package_name: "@company/cms-client"
    output: ./sdk/typescript
    features:
      - type_safe_queries
      - auto_pagination
      - caching_layer
      - retry_logic

    example_usage: |
      import { CmsClient } from '@company/cms-client';

      const client = new CmsClient({
        apiKey: process.env.CMS_API_KEY,
        baseUrl: 'https://api.cms.example.com'
      });

      // Get content
      const article = await client.content.getBySlug('article', 'my-post');

      // Query with filters
      const articles = await client.content.list({
        type: 'article',
        filter: { 'taxonomy.category': 'news' },
        pageSize: 10
      });

      // GraphQL query
      const result = await client.graphql`
        query GetPage($path: String!) {
          pageByPath(path: $path) {
            title
            zones {
              name
              widgets {
                ... on RichTextWidget {
                  content
                }
              }
            }
          }
        }
      `({ path: '/about' });

  # C# SDK
  csharp:
    package_name: "Company.Cms.Client"
    output: ./sdk/csharp
    target_framework: net8.0
    features:
      - strongly_typed
      - async_await
      - di_integration

  # OpenAPI spec
  openapi:
    output: ./openapi.yaml
    version: "3.1.0"
    servers:
      - url: https://api.cms.example.com/v1
        description: Production
      - url: https://api.staging.cms.example.com/v1
        description: Staging

API Design Checklist

REST API

• Resources follow REST conventions
• Consistent URL patterns
• Proper HTTP methods used
• Pagination implemented
• Filtering and sorting supported
• Error responses standardized
• HATEOAS links included

GraphQL API

• Schema well-organized
• Proper use of interfaces/unions
• Relay pagination for lists
• DataLoaders for N+1 prevention
• Input validation
• Complexity limits set
• Persisted queries for production

Security

• Authentication configured
• Authorization rules defined
• Rate limiting implemented
• CORS configured
• API versioning strategy
• Audit logging enabled

Performance

• Caching strategy defined
• CDN integration
• Compression enabled
• Response size limits
• Query complexity limits

Skills to Invoke

For detailed patterns:

• headless-api-design - REST/GraphQL patterns
• content-type-modeling - Content schemas for API
• cdn-media-delivery - Media URL generation