Real-Time Collaboration API Example

GraphQL API for a collaborative document editor demonstrating multiple subscriptions, WebSocket configuration, trigger descriptions, and complexity hints for rate limiting.

February 4, 2026

This example demonstrates a real-time collaborative document editing API. It showcases multiple subscription types, detailed trigger descriptions, WebSocket server configuration, and complexity hints for managing high-frequency events.

API Overview

The Collaboration API enables:

Document Editing - Real-time collaborative text editing
Cursor Tracking - Live cursor positions for all participants
Presence - User join/leave notifications
Comments - Inline comments and discussions

Server Configuration

The API requires both HTTP and WebSocket endpoints:

{
  "id": "api-collab-001",
  "name": "Collaboration API",
  "description": "Real-time collaborative document editing with presence, cursors, and comments.",
  "version": "1.0.0",
  "servers": [
    {
      "id": "production",
      "url": "https://collab.example.com/graphql",
      "wsUrl": "wss://collab.example.com/graphql",
      "description": "Production environment with global CDN",
      "healthCheckUrl": "https://collab.example.com/health",
      "introspectionEnabled": false
    },
    {
      "id": "regional-eu",
      "url": "https://eu.collab.example.com/graphql",
      "wsUrl": "wss://eu.collab.example.com/graphql",
      "description": "European region for lower latency",
      "introspectionEnabled": false
    }
  ],
  "tags": ["collaboration", "real-time", "documents"]
}

Subscriptions

The API provides four subscription types for different real-time events:

Complexity and Rate Limiting

Subscription complexity values help manage server resources:

Subscription	Complexity	Typical Event Rate	Resource Impact
documentEdited	5	10-50 events/second during active editing	Moderate bandwidth
cursorMoved	2	5-10 events/second per active user	Low bandwidth, high frequency
userPresenceChanged	1	1-2 events/minute	Minimal impact
commentAdded	3	Occasional	Low frequency, moderate payload

Authentication

The API uses Bearer token authentication with WebSocket connection parameters:

{
  "authSchemes": [
    {
      "id": "bearer",
      "type": "bearer",
      "description": "JWT token for user authentication. Pass as 'Authorization' header for HTTP or in connection_init payload for WebSocket.",
      "bearerFormat": "JWT"
    }
  ],
  "defaultAuthRequirements": [
    [{ "schemeId": "bearer" }]
  ]
}

For WebSocket connections, pass the token in the connection initialisation:

{
  "type": "connection_init",
  "payload": {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs..."
  }
}

Query and Mutation Examples

What This Example Demonstrates

Feature	How It's Used
Multiple Subscriptions	Four distinct subscription types for different event streams
Trigger Descriptions	Detailed explanations of when events fire and what they contain
WebSocket Configuration	wsUrl on servers for subscription connections
Regional Servers	Multiple server entries for geographic distribution
Complexity Hints	Different values based on event frequency and payload size
Event Throttling	Documented throttling rates (50ms for edits, 100ms for cursors)
Connection Authentication	Bearer token in WebSocket connection_init