GraphQL WebSockets
Last updated: 2 minutes read.
Tyk supports GraphQL via WebSockets using the protocols graphql-transport-ws or graphql-ws between client and Tyk Gateway.
Before this feature can be used, WebSockets need to be enabled in the Tyk Gateway configuration. To enable it set http_server_options.enable_websockets to true in your tyk.conf file.
In order to upgrade the HTTP connection for a GraphQL API to WebSockets by using the graphql-transport-ws protocol, the request should contain following headers:
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Key: <random key>
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: graphql-transport-ws
Messages
The connection needs to be initialised before sending Queries, Mutations, or Subscriptions via WebSockets:
{ "type": "connection_init" }
Always send unique IDs for different Queries, Mutations, or Subscriptions.
For Queries and Mutations, the Tyk Gateway will respond with a complete message, including the GraphQL response inside the payload.
{ "id": "1", "type": "complete" }
For Subscriptions, the Tyk Gateway will respond with a stream of next messages containing the GraphQL response inside the payload until the data stream ends with a complete message. It can happen infinitely if desired.
Note
Be aware of those behaviors:
- If no
connection_initmessage is sent after 15 seconds after opening, then the connection will be closed. - If a duplicated ID is used, the connection will be closed.
- If an invalid message type is sent, the connection will be closed.
Examples
Sending queries
{"id":"1","type":"subscribe","payload":{"query":"{ hello }"}}
Sending mutations
{"id":"2","type":"subscribe","payload":{"query":"mutation SavePing { savePing }"}}
Starting and stopping Subscriptions
{"id":"3","type":"subscribe","payload":{"query":"subscription { countdown(from:10) }" }}
{"id":"3","type":"complete"}
Connection: Upgrade
Upgrade: websocket
Sec-WebSocket-Key: <random key>
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: graphql-ws
Messages
The connection needs to be initialised before sending Queries, Mutations, or Subscriptions via WebSockets:
{ "type": "connection_init" }
Always send unique IDs for different Queries, Mutations, or Subscriptions.
For Queries and Mutations, the Tyk Gateway will respond with a complete message, including the GraphQL response inside the payload.
For Subscriptions, the Tyk Gateway will respond with a stream of data messages containing the GraphQL response inside the payload until the data stream ends with a complete message. It can happen infinitely if desired.
Examples
Sending queries
{"id":"1","type":"start","payload":{"query":"{ hello }"}}
Sending mutations
{"id":"2","type":"start","payload":{"query":"mutation SavePing { savePing }"}}
Starting and stopping Subscriptions
{"id":"3","type":"start","payload":{"query":"subscription { countdown(from:10) }" }}
{"id":"3","type":"stop"}
Upstream connections
For setting up upstream connections (between Tyk Gateway and Upstream) please refer to the GraphQL Subscriptions Key Concept.