Subscriptions

The Chargetrip API relies on GraphQL technology, so some requests use a subscription mechanism. Unlike queries or mutations, subscriptions are long-lasting operations and can change their result over time. These operations are handled by a websocket. Authenticating and communicating with this websocket is different than a regular query or mutation. Let us go over it in detail.

Library usage

The guide below is for those that do not opt in on a library like Apollo GraphQL or Graphql-ws. If you do use a library, skip this and use their documentation.

Initialize the websocket

To get started with the websocket, you must first initialize a connection. It is important that you set the correct WebSocket protocol. We support the graphql-ws and the graphql-transport-ws as Sec-WebSocket-Protocol. The latter is preferred. Each of these protocols uses a different base url. The graphql-ws protocol uses wss://api.chargetrip.io/graphql, the graphql-transport-ws uses wss://api.chargetrip.io/subscription.

wscat -c wss://api.chargetrip.io/graphql -s graphql-ws

wscat -c wss://api.chargetrip.io/subscription -s graphql-transport-ws

Authorization on the websocket

Now that we have opened our connection, we need to authorize ourselves. We can do this by sending a message with the correct type and payload. The type will need to be init and your payload must contain your x-client-id. In combination, it will look like this;

{ "type":"connection_init", "payload": { "x-client-id": "Your client id here" } }

If everything was correct, you will receive the following message from the websocket; { "type": "connection_ack" }.

Communicating on the websocket

With all configuration done you're finally ready to send subscriptions and receive useful data. This is almost identical to the authorization, but with one exception! You will need to add id set to any unique identifier in your message. The id will be returned so you are ensured you got the right message back. To give you an idea of how this looks, we will be using our routeUpdatedById subscription as an example, and only requesting its processing status.

{ "id": "1", "type": "start", "payload": { "query": "subscription routeUpdatedById { routeUpdatedById(id: \"Your route id here\") { status } }", "variables": { "id": "Your route id here"} } }

If everything was correct and you set the routeId in variables and inside your query, the websocket will respond with an object that contains the status. For more information about the route subscription and responses have a look at the route section. If you did not set your routeId in variables, there will be no response from the server.

Disconnecting the websocket

Last but not least; if you got the result you were looking for, don't forget to close the connection! You can do this by pressing ctrl + c or cmd + c in your terminal.