Concepts

Versioning

As outlined in our values, every non-backward-compatible change to SyncRelay's APIs will be published as a new version, including documentation about the changes, and announced in the changelog. API versions follow a date-based scheme, with the year and month of when the changes were made available (e.g. 2021.6 for the version published in June of 2021).

While we try to limit breaking changes, adding new features or deprecating previous ones for security and stability considerations may require it, and versioning allows us to release these changes in a structured and transparent process.

Since versioning is a first-class citizen in our product, every project is set to a specific version, which influences message payloads, and the available set of features that can be used with the SyncRelay API and Live Endpoint. When a new version is released, we'll communicate a reasonable transition period in which you can upgrade your applications, after which we will end support for the previous version.

Organization

In an organization, you can create projects and access tokens. Each organization is bound to service quotas, limiting the usage of certain features like the number of projects or consumers. Access control for teams of any scale is managed with granular, role-based permissions and applies the same way to organization members and access tokens. Audit logs track changes in an organization.

Project

A project is a namespaced container for any interaction within SyncRelay and should be used for one environment or use case. You can create many projects in an organization and adjust permissions, so specific actors may only perform actions in their assigned projects.

Consumer

SyncRelay allows consumers to receive messages on topics they are permitted to subscribe to. Similar to the PubSub design pattern, consumers subscribe to topics and then receive messages dispatched in these.

Live Endpoint

To receive a real-time of events in the form of messages, consumers connect to the Live endpoint using WebSockets.

You can retrieve the live endpoint for your project by clicking Copy Live URL on the project page. Doing this will copy your project's endpoint URL to the clipboard, which roughly looks like wss://live.syncrelay.com/2021.6/projects/project-id/ws and will change only when you upgrade to a new API version.

After connecting to the Live endpoint, SyncRelay will issue periodic health check messages using the PING message kind, which the client is expected to respond to using PONG messages.

SyncRelay API

The SyncRelay API is a GraphQL-based endpoint exposing functionality to dispatch messages, authorize consumers, and perform other actions related to project, organization, or account management. A reference to the current version can be found here.

Consumer Authorization

To establish a connection to SyncRelay, clients are required to include a valid consumer token, either appended to your project's Live Endpoint URL or supplied as an Authorization Bearer header. Enforcing every consumer to be authorized allows SyncRelay to secure project endpoints and provide predictable performance.

When a user begins their session, your application should validate the scope they are allowed to access, and perform the authorizeConsumer operation to retrieve a consumer token valid for an hour after which it will have to be replaced by a newer token. This token may then be passed on to the client, which then connects to the Live Endpoint.

Consumer token as URL parameter

URL: wss://live.syncrelay.com/.../ws?token=<consumer token>

Setting the token as part of the URL is supported by every WebSocket client.

Consumer token passed in header

URL: wss://live.syncrelay.com/.../ws and header Authorization: Bearer <consumer token>

Access Tokens

Access tokens can be created in an organization and assigned multiple permissions, including the ability to authorize consumers and send messages. You can only view the token content after creating an access token. Once created, tokens can be rolled in case you require a new secret.

SyncRelay access tokens are strings starting with sra_ followed by a sequence of characters identifying your token. Make sure never to expose your access tokens to the public, and in case of an accident, roll or delete the access token.

Topics

Topics are defined in a hierarchy, starting with the root topic /. Consumers subscribed to this topic will receive all messages in your project.

When you are interested in granular message delivery, for example only notifications for a certain user, you could design your application to use /users/<user id>/notifications to dispatch notifications to.

An example topic hierarchy for a chat application could look like the following

/ users / user-abc / notifications
/ chats / group-xyz / messages

A consumer subscribed to /users/user-abc will receive all messages to this topic and its sub-topics, such as /notifications.

Messages

Messages can be dispatched manually via the project overview, or programmatically by using the SyncRelay API. Sent messages are persisted for a period determined by the service quotas of the project. Retaining messages allows us to deliver them even if a client disconnects while the message is in flight.