Realtime with GraphQL subscriptions

This will be a short chapter where we want to provide some tips on how you can test the realtime abilities of GraphQL subscriptions live in a Playground.

What are GraphQL Subscriptions?

Subscriptions are a GraphQL feature that allows the server to send data to the clients when a specific event happens on the backend. Subscriptions are usually implemented with WebSockets, where the server holds a steady connection to the client. That is, the Request-Response-Cycle that we used for all previous interactions with the API is not used for subscriptions. Instead, the client initially opens up a steady connection to the server by specifying which event it is interested in. Every time this particular event happens, the server uses the connection to push the data that’s related to the event to the client.

Using Subscriptions in a Playground

You’ll now write and send a subscription in a Playground. Then, in a different tab in the same Playground, you can send a mutation and observe what’s happening to the subscription in the initial tab.

This time, instead of directly seeing the results of the operation on the right, the Play-button turns into a stop button and a loading indicator appears in the right pane.

The subscription is now active, meaning that every time a mutation is performed on the Link type, the server will push the data that you specified in the subscription payload to you.

Notice that in the payload, the mutation field represents the kind of mutation that’s happening, so that’s either of three values: CREATED, UPDATE or DELETED.

The node will hold the information about the Link that was created or modified. If the DELETED operation occurs, you’d have to include the previousValues in the payload to retrieve information about the deleted node. This could look as follows:

subscription {
  Link {
    mutation # contains CREATED, UPDATED or DELETED
    previousValues {
      id
      description
      url
    }
  }
}

Now switch back to the previous tab where the subscription is still running.

You should see the following data in the right pane:

{
  "data": {
    "Link": {
      "mutation": "CREATED",
      "node": {
        "id": "cj4nbwmxwc2bp0194tgnf8krl",
        "description": "Flexible GraphQL client",
        "url": "http://dev.apollodata.com/"
      }
    }
  }
}

Exactly as with a query, the structure of the data that’s received on the client matches the structure of the payload that you defined in the subscription.

Another tip: Often times you’ll only be interested in specific mutations, e.g. when new items are being created. However, this current subscription actually also fires for updated and deleted mutations. To prevent that, you can include a filter in the subscription to make sure you only receive data when new links are created:

subscription {
  Link(filter: {
    mutation_in: [CREATED]
  }) {
    mutation # contains CREATED, UPDATED or DELETED
    node {
      id
      description
      url
    }
  }
}

Next Chapter

Summary

You learned how to build a GraphQL server with Graphcool and best practices for filters, authentication, pagination and subscriptions.

Go to next chapter