How to run GraphQL subscriptions in API Spector

Queries and mutations are request and response, but a subscription is a live stream over WebSocket. API Spector now runs GraphQL subscriptions using the graphql-ws protocol (graphql-transport-ws), the same one most GraphQL servers speak.

Write the subscription

Create a GraphQL request and write a subscription operation in the query editor, for example:

subscription {
  messageAdded(room: "general") {
    id
    text
  }
}

As soon as the query is a subscription, a Subscription (WebSocket) panel appears below the Variables box.

Point it at the endpoint

The panel has a WebSocket URL field. Leave it empty to use the request URL with a ws or wss scheme, or type the subscription endpoint, which is often the same /graphql path on a ws or wss scheme. The field understands {{variables}}, so {{baseUrl}} resolves the same way it does elsewhere.

For auth, the request headers are sent on the WebSocket handshake. If the server expects a token in the connection_init payload instead, open Connection params (JSON) and set it, for example {"authToken": "{{token}}"}.

Run it

Click Subscribe. API Spector opens the WebSocket, performs the graphql-ws handshake, and starts the subscription. Each event streams into the panel as formatted JSON, GraphQL errors show in red, and a note marks when the stream completes. Click Stop to end it.

Subscription variables use the same Variables box as queries, so a subscription that takes arguments works the same way a parameterized query does.

Why it helps

Realtime GraphQL used to mean leaving your API client to test it. Now the subscription lives next to your queries and mutations, against the same schema and the same variables, and you watch it stream without switching tools.