GraphQL Subscriptions

Last updated: 2 minutes read.

Tyk natively supports also GraphQL subscriptions, so you can expose your full range of GQL operations using Tyk Gateway. Subscriptions support was added in v4.0.0 in which graphql-ws protocol support was introduced.

With the release of Tyk v4.3.0 the number of supported subscription protocols has been extended.

In Tyk subscriptions are using the WebSocket transport for connections between the client and Gateway. For connections between Gateway and upstream WebSockets or SSE can be used.

Supported transports and protocols

Transport Protocol
WebSockets graphql-ws (default, no longer maintained)
WebSockets graphql-transport-ws
HTTP Server-Sent Events (SSE)

Setting up subscription types via API definition

Subscription types or subscription transports/protocols are set inside the graphql section of the API definition.

Depending on whether you want to configure GraphQL proxy-only, UDG, or GraphQL Federation there are different places for the configuration option.

The values for subscription types are the same on all API types:

  • graphql-ws
  • graphql-transport-ws
  • sse (Server-Sent Events)
GraphQL Proxy
{
  ...,
  "graphql": {
    ...,
    "proxy": {
      ...,
      "subscription_type": "graphql-ws"
    }
  }
}
Universal Data Graph
{
  ...,
  "graphql": {
    ...,
    "engine": {
      ...,
      "data_sources": [
        ...,
        {
          ...,
          "subscription_type": "sse"
        }
      ]
    }
  }
}
Federation
{
  ...,
  "graphql": {
    ...,
    "supergraph": {
      ...,
      "subgraphs": [
        ...,
        {
          ...,
          "subscription_type": "graphql-transport-ws"
        }
      ]
    }
  }
}

Note

If the upstream subscription GraphQL API is protected please enable the authentication via query params to pass the header through.

There is no need to enable subscriptions separately. They are supported alongside GraphQL as a standard. The only requirement for subscriptions to work is to enable WebSockets in your Tyk Gateway configuration file.

Here’s a general sequence diagram showing how subscriptions in Tyk work exactly:

Tyk Subscriptions workflow