Logo
NeoArc Studio

Subscriptions

Document real-time GraphQL subscriptions with trigger descriptions, WebSocket configuration, and event-driven patterns.

Subscriptions enable real-time data streaming from server to client over persistent connections. Unlike queries and mutations which follow request-response patterns, subscriptions maintain a connection and push data when events occur.

Subscription Concepts

Trigger Descriptions

The triggerDescription property documents what events cause the subscription to emit data. This is essential for consumers to understand when they will receive updates.

{
  "id": "sub-order-status-001",
  "name": "orderStatusChanged",
  "operationType": "subscription",
  "description": "Streams order status updates in real-time.",
  "triggerDescription": "Emitted when an order's status changes from one state to another. Events include: PLACED, CONFIRMED, SHIPPED, DELIVERED, CANCELLED. Each event includes the previous and new status values.",
  "returnTypeName": "OrderStatusEvent!",
  "arguments": [
    {
      "id": "arg-order-id",
      "name": "orderId",
      "typeName": "ID",
      "nullable": false,
      "description": "The order to monitor for status changes"
    }
  ]
}

Common Subscription Patterns

WebSocket Configuration

Subscriptions require a WebSocket endpoint. Configure this in your API's server definition:

{
  "servers": [
    {
      "id": "production",
      "url": "https://api.example.com/graphql",
      "wsUrl": "wss://api.example.com/graphql",
      "description": "Production GraphQL endpoint",
      "introspectionEnabled": false
    }
  ]
}

Subscription Example

{
  "id": "sub-doc-edit-001",
  "name": "documentEdited",
  "operationType": "subscription",
  "description": "Streams real-time edits to a collaborative document. Includes the editing user, changed section, and operation type.",
  "triggerDescription": "Emitted when any user makes an edit to the document. Events include character insertions, deletions, formatting changes, and cursor movements. Events are batched every 100ms to reduce network traffic.",
  "returnTypeName": "DocumentEditEvent!",
  "returnTypeNullable": false,
  "arguments": [
    {
      "id": "arg-doc-id",
      "name": "documentId",
      "typeName": "ID",
      "nullable": false,
      "description": "The document to monitor for edits"
    },
    {
      "id": "arg-exclude-self",
      "name": "excludeSelf",
      "typeName": "Boolean",
      "nullable": true,
      "defaultValue": "true",
      "description": "Whether to exclude events from the current user"
    }
  ],
  "exampleQuery": "subscription WatchDocument($docId: ID!) {\n  documentEdited(documentId: $docId) {\n    userId\n    userName\n    operation\n    position\n    content\n    timestamp\n  }\n}",
  "exampleVariables": "{\n  \"docId\": \"doc-456\"\n}",
  "exampleResponse": "{\n  \"data\": {\n    \"documentEdited\": {\n      \"userId\": \"user-789\",\n      \"userName\": \"Alice\",\n      \"operation\": \"INSERT\",\n      \"position\": 142,\n      \"content\": \"Hello, world!\",\n      \"timestamp\": \"2024-01-15T14:30:00Z\"\n    }\n  }\n}",
  "complexity": 5,
  "tags": ["collaboration", "real-time"]
}

Complexity Considerations

Subscription complexity affects server resource usage differently than queries:

Authentication for Subscriptions

Subscription authentication typically works differently than HTTP requests:

  • Connection initialisation - Token passed during WebSocket handshake
  • Per-subscription auth - Some systems authenticate each subscription
  • Token refresh - Document how long-lived connections handle token expiry

Document the authentication flow in your security configuration.

Related Content