Data & State Endpoints

Version: 0.1.0

Table of contents

  1. Overview
  2. Data Endpoints
    1. Request Format
    2. Response Format
    3. Pagination
    4. Filtering
    5. Sorting
    6. Search
  3. State Endpoints
    1. Request Format
    2. Response Format
    3. Scoped State
  4. Real-Time Updates
    1. Server-Sent Events (Recommended)
    2. WebSocket (Optional)
    3. Polling Fallback
  5. Idempotency and Safety
    1. Safe Methods
    2. Cache Control
  6. Error Handling
    1. Error Response Format
    2. Standard Error Codes
  7. Content Types
    1. Request
    2. Response

Overview

FieldSpace channels expose data and state through HTTP endpoints. This document specifies the requirements for data access, state inspection, and real-time updates.

Data Endpoints

Data endpoints serve read-only content. They are the primary mechanism for channels to expose collections and items.

Request Format 

GET /api/videos
Accept: application/json
Authorization: Bearer <token>

Response Format 

{
  "data": [...],
  "meta": {
    "total": 100,
    "page": 1,
    "per_page": 20,
    "has_more": true
  }
}

Pagination

Paginated endpoints must support:

Parameter Type Description
page integer Page number (1-indexed)
per_page integer Items per page (max 100)
cursor string Opaque cursor for cursor-based pagination

Channels should prefer cursor-based pagination for large datasets.

Filtering

Filterable endpoints accept query parameters matching schema properties:

GET /api/videos?category=music&duration_min=60

Sorting

Sortable endpoints accept sort and order parameters:

GET /api/videos?sort=published_at&order=desc

Searchable endpoints accept a q parameter:

GET /api/videos?q=cooking+tutorial

State Endpoints

State endpoints expose the channel’s current condition. Unlike data endpoints, state represents mutable, real-time information.

Request Format 

GET /api/state
Accept: application/json
Authorization: Bearer <token>

Response Format 

{
  "channel_id": "com.example.media",
  "timestamp": "2026-01-21T10:30:00Z",
  "state": {
    "playback": {
      "status": "playing",
      "position_seconds": 142,
      "duration_seconds": 3600,
      "current_item_id": "video-123"
    },
    "queue": {
      "items": ["video-123", "video-456"],
      "position": 0
    }
  }
}

Scoped State

Channels may expose state at different scopes:

GET /api/state                    # Full channel state
GET /api/state/playback           # Playback state only
GET /api/state/queue              # Queue state only

Real-Time Updates

Channels may support real-time state updates via Server-Sent Events (SSE) or WebSocket.

GET /api/state/stream
Accept: text/event-stream

Response:

event: state_update
data: {"playback":{"status":"playing","position_seconds":143}}

event: state_update
data: {"playback":{"position_seconds":144}}

WebSocket (Optional) 

ws://channel.example.com/api/state/ws

Message format:

{
  "type": "state_update",
  "path": "playback.position_seconds",
  "value": 145,
  "timestamp": "2026-01-21T10:30:05Z"
}

Polling Fallback

When real-time updates are unavailable, clients must fall back to polling. Channels declare recommended intervals:

{
  "metadata": {
    "refresh_interval_seconds": 5
  }
}

Clients should respect these intervals and must not poll more frequently than once per second.

Idempotency and Safety

Safe Methods

All data and state endpoints use GET requests, which are:

  • Safe: No side effects
  • Idempotent: Same request yields same result
  • Cacheable: Responses may be cached per HTTP headers

Cache Control

Channels should include appropriate cache headers:

Cache-Control: max-age=60, stale-while-revalidate=300
ETag: "abc123"
Last-Modified: Tue, 21 Jan 2026 10:00:00 GMT

Clients should use conditional requests:

GET /api/videos
If-None-Match: "abc123"

Error Handling

Error Response Format 

{
  "error": {
    "code": "not_found",
    "message": "Video not found",
    "details": {
      "video_id": "xyz-999"
    }
  }
}

Standard Error Codes

HTTP Status Code Description
400 bad_request Invalid request parameters
401 unauthorized Authentication required
403 forbidden Insufficient permissions
404 not_found Resource not found
429 rate_limited Too many requests
500 internal_error Channel error
503 unavailable Channel temporarily unavailable

Content Types

Request

Clients must send:

Accept: application/json

Response

Channels must respond with:

Content-Type: application/json; charset=utf-8

FieldSpace Protocol v0.1.0 — Data & State Endpoints