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": "2019-04-16T14:37:24.979Z",
    "updatedAt": "2019-04-16T14:37:24.979Z"
  }]
}

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": "2019-04-16T14:37:24.98Z",
  "updatedAt": "2019-04-16T14:37:24.98Z"
}

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": "2019-04-16T14:37:24.98Z",
  "updatedAt": "2019-04-16T14:37:24.98Z"
}

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": "2019-04-16T14:37:24.982Z",
  "updatedAt": "2019-04-16T14:37:24.982Z"
}

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": "2019-04-16T14:37:24.984Z",
  "updatedAt": "2019-04-16T14:37:24.984Z"
}