Ringier Event Bus

# Sending events via the bus API

You will find below the information required to send events to the Ringier Event Bus via its API.

# Base URL

Here is the bus API base URL for the staging and production environments:

  • Staging: https://bus.staging.ritdu.tech/v1
  • Production: https://bus.ritdu.net/v1

# /login endpoint

To authenticate, call the /login endpoint with your username, password and node id in a JSON object in order to retrieve a token. We assume that you have registered a node on the bus. If not, kindly refer to the section Register on the bus.

POST /login

# Parameters

# Version 2.0.0 (current)

Name Type Required
username string ✓
password string ✓
node_id string ✓

# Call example

{
  "username": "Jack",
  "password": "hd8kjd-JNH;sE9KEu8y6",
  "node_id": "04f9f5d9-d84c-4636-acae-2067eee4d81f"
}

# Responses

The token retrieved must be cached and included as x-api-key in the header when sending events.

The /login endpoint must only be called again to retrieve a new token if it expires, i.e. you get a 401 response code from the bus when sending an event.

# /events endpoint

To send event(s) into the bus via the API, POST an array of events to the /events endpoint.

POST /events

# Parameters

# Version 2.0.0 (current)

Name Type Required Description
events array of strings ✓ Array of event names.
from string ✓ Your node id. It must be the same as the one used to authenticate.
reference string ✓ A unique reference for the event instance.
created_at string ✓ Date and time when the event was created, including timezone, following ISO 8601 (YYYY-MM-DDThh:mm:ss.sTZD) (opens new window), e.g.: "2022-05-09T16:59:14+02:00"
payload object ✓ JSON payload relevant to the specific event(s). See the specifications.
version string ✓ Event version. The version described here is "2.0.0".
route string Together with the event name, this field can be used to determine where the event will be routed. Optional and defaulted to empty. Learn more.

# Call example

[
  {
    "events": ["EventName"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "123456",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {},
    "version": "2.0.0",
    "route": ""
  }
]

# Responses

# Queueing and retrying

If you choose to send events via the bus API, events must be queued on the sender side to achieve the lowest risk of failure. We recommend implementing basic queuing with services such as AWS SQS or any other queuing system readily available in your development framework.

Should the client be unable to send the event to the bus (possible reasons include connectivity issues), it shall retry using exponential backoff.

# Batch events

If you want to send several events with the same payload, you can send them in one object.
Example of use case: one user creates an account, ticks the newsletter subscription box and is logged in automatically.

[
  {
    "events": ["UserCreated", "NewsletterSubscribed", "UserLogin"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "123456",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {
      "user": {}
    },
    "version": "2.0.0"
  }
]

If you batch several events each with its own payload, you can send several objects:

[
  {
    "events": ["Event1"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "123456",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {},
    "version": "2.0.0"
  },
  {
    "events": ["Event2"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "123457",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {},
    "version": "2.0.0"
  },
]

Event and payload specifications
View events sent
Event routing
Testing
Other methods to send events to the bus