Live Message Server - Developer Guidelines

Authentication

To access the API, you need to generate an authentication token. You can do this by making a POST request to the `/generateToken` endpoint.

  curl -X POST -H "Content-Type: application/json" \
  -d '{"clientId": "your_client_id", "clientSecret": "your_client_secret", "roles": ["publisher", "subscriber"]}' \
  http://localhost:3000/generateToken
  

Replace your_client_id, your_client_secret, and roles with your actual values. The roles array can include publisher and/or subscriber.

To obtain your clientId and clientSecret, you need to contact the server administrator. They will provide you with these credentials, which are unique to your application.

Publishing Messages

To publish a message, make a POST request to the `/publish` endpoint with the following parameters:

• channel: (required) The channel to publish the message to.
• message: (required) The message to publish. This should be a JSON object.
• expiryTime: (optional) The expiry time for the message. If not provided, the message will not expire. If provided, it can be a number (representing minutes) or a string in one of the following formats:
  • number + "m": number of minutes
  • number + "h": number of hours
  • number + "d": number of days

  curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_access_token" \
  -d '{"channel": "your_channel", "message": {"text": "Your message"}, "expiryTime": "1h"}' \
  http://localhost:3000/publish
  

Replace your_access_token, your_channel, and Your message with your actual values. The expiryTime parameter is optional.

Subscribing to Messages

To subscribe to a channel, use the subscribe event on your WebSocket connection:

    socket.emit('subscribe', 'your_channel', { receiveLastMessage: true });
  

Replace your_channel with the channel you want to subscribe to. The receiveLastMessage option is optional and defaults to false. If set to true, the server will emit the last message published to the channel when you subscribe.

Unsubscribing from Messages

To unsubscribe from a channel, use the unsubscribe event on your WebSocket connection:

    socket.emit('unsubscribe', 'your_channel');
  

Replace your_channel with the channel you want to unsubscribe from.

Receiving Messages

When a message is published to a channel you are subscribed to, you will receive a message event on your WebSocket connection with the following

    console.log(data);
  

The data object will contain the channel, message, and timestamp of the message.

Server Administrator

The server administrator is responsible for setting up and managing the Live Message Server. This includes configuring the server, managing clients, and ensuring the security of the system.

Setting up Clients

The server administrator needs to set the CLIENTS environment variable to configure the allowed clients. The CLIENTS variable should be a base64 encoded JSON string representing an array of client configurations. Each client configuration should be an object with the following properties:

• id: The client ID.
• secret: The client secret.
• origins: An array of origins for the client application. This allows for multiple origins to be specified for a single client.

For example, to add a client with the ID my-client, the secret my-secret, and origins https://my-client.com and http://localhost:3001, the CLIENTS environment variable should be set to:

  echo '[{"id": "my-client", "secret": "my-secret", "origins": ["https://my-client.com", "http://localhost:3001"]}]' | base64
  

The origins value represents the domains or URLs of the client application. It is used to restrict access to the server based on the origin of the client application. The server will only allow clients with matching origins to subscribe to channels.