API Reference (2021.6)

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": {}
}