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.

Step 1

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, as described over here. Each of these protocols uses a different base url.

Subscriptions / Initialise using graphql-transport-ws

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

Subscriptions / Initialise using graphql-ws

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

Step 2

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 and x-app-id. If everything was correct, you will receive the following message from the websocket; { "type": "connection_ack" }.

Subscriptions / Authorization payload

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

Step 3

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.

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.

Subscriptions / Communicating

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

Step 4

Closing the connection

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.