SyncRelay API
The SyncRelay GraphQL API is available at https://api.syncrelay.com/graphql
.
Authorization
Using access tokens, you can access the SyncRelay API. Create an access token in your organization to access the API and supply it in the Authorization
header of your request, as a Bearer
token.
Authorizing Consumers
Whenever a client establishes a connection to SyncRelay, it must include a consumer token. This token is used to verify the integrity of the client, including whether it is authorized to subscribe to certain topics of a project.
To retrieve a consumer token, your application back-end should send the following GraphQL mutation:
mutation ($projectId: ID!, $allowedTopics: [String!]!) {
authorizeConsumer(
data: { projectId: $projectId, allowedTopics: $allowedTopics }
) {
consumerToken
}
}
The generated consumer token is valid for an hour after which it has to be renewed.
Sending messages
To send a message in your project, you can use the following GraphQL mutation:
mutation ($projectId: ID!, $topic: String!, $kind: String!, $payload: Json!) {
sendMessage(
data: {
projectId: $projectId
topic: $topic
kind: $kind
payload: $payload
}
) {
sentMessage {
id
}
}
}
This will persist the message and dispatch it to all connected clients subscribed to the topic you passed.
Live Endpoint
The Live Endpoint supports WebSockets and can be accessed by connecting to the URL copied in the project overview. In the following examples, we'll use TypeScript to establish a connection to the Live Endpoint, receive messages, and respond to health checks. As we do not make use of very language-specific code, you should be able to use any platform that supports WebSockets in a similar fashion.
Connecting
Open a WebSocket connection to the live endpoint, make sure to include the consumer token in the URL parameter token
or in the Authorization
header.
// Obtain consumer token from your application's back-end
const consumerToken = '...';
// Establish connection
const socket = new WebSocket(
`wss://live.syncrelay.com/2021.6/projects/<projectId>/ws?token=${consumerToken}`
);
Subscribing to topics
Once you received the SESSION_READY
message, you can send a message of kind TOPIC_SUBSCRIBE
using the WebSocket connection.
// Subscribe to one or more topics
socket.send(
JSON.stringify({
kind: 'TOPIC_SUBSCRIBE',
payload: {
topics: [<topics you want to subscribe to>],
},
})
);
Once sent and processed, the live endpoint will send a TOPIC_SUBSCRIBE_ACK
message.
Responding to health checks
Make sure your socket connection responds to health checks in time. If it does not, your client will be disconnected after a specific timeout.
socket.onmessage = ev => {
const receivedMessage = JSON.parse(ev.data);
switch (receivedMessage.kind) {
case 'PING': {
socket.send(
JSON.stringify({
kind: 'PONG',
payload: {},
})
);
break;
}
}
};
Receiving messages
Messages dispatched in your project will be transmitted to connected clients as a WebSocket message of kind SENT_MESSAGE
. The payload contains the sent message, including its id, topic, kind, and payload.
ws.onmessage = ev => {
const receivedMessage = JSON.parse(ev.data);
switch (receivedMessage.kind) {
// ...
case 'SENT_MESSAGE': {
// TODO Handle message here
break;
}
// ...
}
};
Messages
Dispatched from the Live endpoint
Your client should be prepared to handle the following messages sent from the Live endpoint.
SESSION_READY
This message indicates that the session has been established and the client will receive messages it is subscribed to. You should subscribe to topics only after receiving this message.
SENT_MESSAGE
You will receive this message when a message is dispatched to your project. The payload contains the sent message, including its id, topic, kind, and payload.
{
"version": "2021.6",
"kind": "SENT_MESSAGE",
"meta": {
"sessionId": "1viOC13PSq0AFfFKmFOsmyaWnIS",
"sentAt": "2021-07-01T18:00:00.785Z"
},
"payload": {
"id": "1viOD4dQjGU6x1jo95YtluBvs2k",
"topic": "/users/1/deliveries/a",
"kind": "delivery_location_changed",
"sentAt": "2021-07-01T18:00:00.729529+00:00",
"payload": {
"delivery": "a",
"location": { "lat": "48.1610706", "long": "11.5838923" }
}
}
}
PING
The live endpoint will send a PING
message periodically to ensure the health of the connection. Respond to this message with a PONG
message.
TOPIC_SUBSCRIBE_ACK
After subscribing to a topic, the live endpoint will send a TOPIC_SUBSCRIBE_ACK
message including the list of topics the client is now subscribed to.
Sent to the live endpoint
The following messages can be sent to the live endpoint from your client.
TOPIC_SUBSCRIBE
Subscribe to one or more topics.
{
"kind": "TOPIC_SUBSCRIBE",
"payload": {
"topics": ["/users/1/deliveries/a"]
}
}
PONG
Respond to a health check by sending a PONG
message.
{
"kind": "PONG",
"payload": {}
}