Knowledge Base

Custom Ids

In order to provide optimal integratability, you can work with custom ids on all resources. When creating these resources, you can pass an id property to the payload. You can then retrieve that resource by its custom id: eg. GET /users/test-bot-1. Valid ids must match ^[0-9a-zA-Z_-]+$ (alpha-numeric, -, _). If you do not provide a custom id, a UUIDv4 will be generated by default.

Custom Properties

Our API resources User and Channel have a properties field, that can be used to store key value pairs to RealMQ objects.

Example Channel Properties:

{
  "id": "test-channel",
  "properties": {
    "type": "group-chat",
    "memberCount": 46,
    "moderators": [{
      "id": "mod-user"
    }]
  }
}

Paginated Lists

Paginated bulk-fetch functionality via listing API methods is supported by all top-level API resources.
For example, you can list users (GET /users) or list channels (GET /channels), etc…
These listing API methods share a common response structure and take at least these two parameters: limit, offset.

Paginated List	Our generalized list response
Int `total`	The amount of accessible items
Int `count`	The number of items in this response
Int `offset`	Start position of the slice relative to all accessible items
Int `limit`	The considered slice limit (min: 0, max: 100, default: 20)
Array `items`	The list of fetched objects

Example User List:

{
  "total": 1026,
  "count": 1,
  "offset": 1025,
  "limit": 20,
  "items": [{
    "id": "test-user",
    "properties": {},
    "isOnline": true,
    "createdAt": "2023-08-01T11:03:42.576Z",
    "updatedAt": "2023-08-01T11:03:42.576Z"
  }]
}

User Resource

A user may be a human, bot, sensor, server etc. and is able to participate in channel communications.

User Schema
String `id`	A Custom Id or autogenerated UUIDv4
Object `properties`	A map of Custom Properties
Boolean `isOnline`	Whether the user is currently connected to the real-time broker.
DateTime `createdAt`	Iso date time of initial creation.
DateTime `updatedAt`	Iso date time of last update.

Example User:

{
  "id": "test-user",
  "properties": {},
  "isOnline": true,
  "createdAt": "2023-08-01T11:03:42.576Z",
  "updatedAt": "2023-08-01T11:03:42.576Z"
}

Channel Resource

Channels are used to broadcast messages. A user may be subscribed to multiple channels.

Channel Schema
String `id`	A Custom Id or autogenerated UUIDv4
Object `properties`	A map of Custom Properties
Object `features`	A feature configuration for this channel
Object `features.persistence`	Persistence settings for this channel
Boolean `features.persistence.enabled`	Whether or not to persist messages for this channel
Boolean `features.persistence.duration`	Period for how long messages are stored for this channel
DateTime `createdAt`	Iso date time of initial creation.
DateTime `updatedAt`	Iso date time of last update.

Example Channel:

{
  "id": "test-channel",
  "properties": {},
  "features": {
    "persistence": {
      "enabled": true,
      "duration": "7d"
    }
  },
  "createdAt": "2023-08-01T11:03:42.576Z",
  "updatedAt": "2023-08-01T11:03:42.576Z"
}

Subscription Resource

A subscription describes the access rights of user on channels. Without a subscription a user can not send or receive messages on a channel.

Subscription Schema
String `id`	A Custom Id or autogenerated UUIDv4
String `channelId`	Channel reference
String `userId`	User reference
Boolean `allowRead`	Whether the user is allowed to read messages from the channel.
Boolean `allowWrite`	Whether the user is allowed to publish messages to the channel
DateTime `createdAt`	Iso date time of initial creation.
DateTime `updatedAt`	Iso date time of last update.

Example Subscription:

{
  "id": "test-subscription",
  "channelId": "test-channel",
  "userId": "test-user",
  "allowRead": true,
  "allowWrite": false,
  "createdAt": "2023-08-01T11:03:42.576Z",
  "updatedAt": "2023-08-01T11:03:42.576Z"
}

Auth Token Resource

A token is issued for one user and grants scope specific REST- & real-time API access rights.

Token Schema
String `id`	A Custom Id or autogenerated UUIDv4
String `scope`	Possible values are `admin` and `user`.
String `userId`	User reference
String `token`	Random security token.
Boolean `isOnline`	Whether this token is currently connected to the real-time broker.
String `description`	Auth token description
DateTime `createdAt`	Iso date time of initial creation.
DateTime `updatedAt`	Iso date time of last update.

Example Token:

{
  "id": "test-token",
  "scope": "user",
  "userId": "test-user",
  "token": "PBCTpLPZkJkpMnA/kV2dgLfNDjgIAcF=",
  "isOnline": true,
  "description": "Some optional desc.",
  "createdAt": "2023-08-01T11:03:42.576Z",
  "updatedAt": "2023-08-01T11:03:42.576Z"
}