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
- 01
wscat -c wss://api.chargetrip.io/subscription -s graphql-transport-ws
Subscriptions / Initialise using graphql-ws
- 01
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
- 01
- 02
- 03
- 04
- 05
- 06
{
"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
- 01
- 02
- 03
- 04
- 05
- 06
- 07
- 08
- 09
- 10
{
"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.