headless-api-design

What this skill does

# Headless API Design

Guidance for designing content delivery APIs for headless CMS architectures, enabling multi-channel content distribution.

## When to Use This Skill

- Designing REST or GraphQL APIs for content delivery
- Implementing preview endpoints for draft content
- Adding localization/i18n to content APIs
- Planning pagination and filtering strategies
- Configuring caching headers for content
- Versioning content APIs

## API Architecture Overview

### Headless CMS API Layers

```text
┌─────────────────────────────────────────────────────────────┐
│                    Content Consumers                         │
│  (Blazor, React, Next.js, Mobile Apps, IoT, Digital Signs)  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Content Delivery API                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │  REST API   │  │ GraphQL API │  │ Preview/Draft API   │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Content Services                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Content   │  │    Media    │  │   Localization      │  │
│  │   Query     │  │   Resolver  │  │   Service           │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Content Repository                        │
│              (EF Core + JSON Columns + Cache)               │
└─────────────────────────────────────────────────────────────┘
```

## REST API Design

### Resource Endpoints

```text
GET    /api/content                    # List all content items
GET    /api/content/{id}               # Get content by ID
GET    /api/content/alias/{path}       # Get content by URL path/alias
GET    /api/content/types/{type}       # List content by type

# Type-specific endpoints
GET    /api/articles                   # List articles
GET    /api/articles/{id}              # Get article
GET    /api/pages                      # List pages
GET    /api/pages/{id}                 # Get page

# Nested resources
GET    /api/articles/{id}/comments     # Get article comments
GET    /api/menus/{id}/items           # Get menu items
```

### Query Parameters

```text
# Pagination
?page=1&pageSize=20                    # Offset pagination
?cursor=eyJpZCI6MTIz&limit=20         # Cursor pagination

# Filtering
?filter[status]=published
?filter[contentType]=Article
?filter[author.id]=abc123
?filter[createdUtc][gte]=2025-01-01

# Sorting
?sort=-publishedUtc                    # Descending
?sort=title                            # Ascending
?sort=category.name,-createdUtc        # Multiple fields

# Field selection (sparse fieldsets)
?fields=id,title,slug,publishedUtc
?fields[article]=title,body
?fields[author]=name,avatar

# Include related resources
?include=author,categories
?include=author.profile
```

### Response Structure

```json
{
  "data": {
    "id": "abc123",
    "type": "Article",
    "attributes": {
      "title": "Getting Started with Headless CMS",
      "slug": "getting-started-headless-cms",
      "body": "<p>Content here...</p>",
      "publishedUtc": "2025-01-15T10:30:00Z",
      "status": "Published"
    },
    "parts": {
      "titlePart": {
        "title": "Getting Started with Headless CMS"
      },
      "seoPart": {
        "metaTitle": "Headless CMS Guide",
        "metaDescription": "Learn how to..."
      }
    },
    "relationships": {
      "author": {
        "data": { "id": "author456", "type": "Author" }
      },
      "categories": {
        "data": [
          { "id": "cat1", "type": "Category" }
        ]
      }
    }
  },
  "included": [
    {
      "id": "author456",
      "type": "Author",
      "attributes": {
        "name": "Jane Doe",
        "bio": "Technical writer..."
      }
    }
  ],
  "meta": {
    "version": "1.0",
    "generatedAt": "2025-01-15T14:22:00Z"
  }
}
```

### Collection Response with Pagination

```json
{
  "data": [...],
  "meta": {
    "totalCount": 156,
    "pageSize": 20,
    "currentPage": 1,
    "totalPages": 8
  },
  "links": {
    "self": "/api/articles?page=1&pageSize=20",
    "first": "/api/articles?page=1&pageSize=20",
    "prev": null,
    "next": "/api/articles?page=2&pageSize=20",
    "last": "/api/articles?page=8&pageSize=20"
  }
}
```

## GraphQL API Design

### Schema Definition

```graphql
type Query {
  # Single item queries
  content(id: ID!): ContentItem
  contentByPath(path: String!): ContentItem

  # Type-specific queries
  article(id: ID!): Article
  articles(
    filter: ArticleFilter
    sort: ArticleSort
    first: Int
    after: String
  ): ArticleConnection!

  page(id: ID!): Page
  pages(parentId: ID): [Page!]!

  menu(id: ID, name: String): Menu
}

interface ContentItem {
  id: ID!
  contentType: String!
  displayText: String
  createdUtc: DateTime!
  modifiedUtc: DateTime!
  publishedUtc: DateTime
  status: ContentStatus!
}

type Article implements ContentItem {
  id: ID!
  contentType: String!
  displayText: String
  createdUtc: DateTime!
  modifiedUtc: DateTime!
  publishedUtc: DateTime
  status: ContentStatus!

  # Parts
  titlePart: TitlePart
  autoroutePart: AutoroutePart
  seoPart: SeoMetaPart

  # Fields
  body: String!
  featuredImage: MediaField
  author: Author
  categories: [Category!]!
  tags: [String!]!
  readTimeMinutes: Int
}

type ArticleConnection {
  edges: [ArticleEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type ArticleEdge {
  node: Article!
  cursor: String!
}

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

input ArticleFilter {
  status: ContentStatus
  categoryId: ID
  authorId: ID
  tags: [String!]
  publishedAfter: DateTime
  publishedBefore: DateTime
  search: String
}

input ArticleSort {
  field: ArticleSortField!
  direction: SortDirection!
}

enum ArticleSortField {
  TITLE
  PUBLISHED_UTC
  CREATED_UTC
  READ_TIME
}
```

### Content Parts as Types

```graphql
type TitlePart {
  title: String!
  displayTitle: String
}

type AutoroutePart {
  path: String!
  isCustom: Boolean!
}

type SeoMetaPart {
  metaTitle: String
  metaDescription: String
  metaKeywords: String
  noIndex: Boolean!
  noFollow: Boolean!
}

type MediaField {
  paths: [String!]!
  urls: [String!]!
  alt: String
  caption: String
  mediaItems: [MediaItem!]!
}

type MediaItem {
  id: ID!
  url: String!
  mimeType: String!
  width: Int
  height: Int
  alt: String
}
```

## Preview API

### Draft Content Endpoint

```text
# Requires authentication/preview token
GET /api/preview/content/{id}
GET /api/preview/content/{id}?version={versionId}

# Preview token in header
Authorization: Bearer <preview-token>
X-Preview-Mode: true
```

### Preview Implementation

```csharp
[ApiController]
[Route("api/preview")]
public class PreviewController : ControllerBase
{
    private readonly IContentService _contentService;
    private readonly IPreviewTokenService _tokenService;

    [HttpGet("content/{id}")]
    public async Task<ActionResult<ContentItemDto>> GetPreview(
        string id,
        [FromHeader(Name = "X-Preview-Token")] string? previewToken,
        [FromQuery] string? version)
    {
        // Validate preview token
        if (!await _tokenService.ValidateTokenAsync(previewToken))
        {
            return Unauthorized();
        }

        // Get draft or specific version
        var content = version != null
            ? await _content