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

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.1.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

200 Success

{
  "token": "8h345lr08Ui2nsAl3aUl3XM8XziD-vJgBu3zgmiFw9IQLEJREr1b0w78534HkDnU0qxjDAIDh9GIsZNLOungL3i0vvprH6pw5ffLYCzcdczQ81bqLuvSF9Hz9UFDXW0i",
  "ttl": 0,
  "name": "Jack"
}

401 Wrong username or password

{
  "code": 401,
  "message": "Login failed"
}

422 Invalid node id

{
  "code": 422,
  "message": "Login failed"
}

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.1.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), e.g.: "2022-05-09T16:59:14+02:00"
debounce_key	string		Key used to debounce consecutive events. When debouncing is enabled on the emitting node, the bus holds events sharing the same `debounce_key` and only routes the latest one (based on `created_at`). Events without a `debounce_key` are routed as normal. Optional.
payload	object	✓	JSON payload relevant to the specific event(s). See the specifications.
version	string	✓	Event version. The version described here is "2.1.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": "a1f4c8e2-7b93-4d6a-9f2c-8e1d3b5a7c90",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "debounce_key": "listing-123456",
    "payload": {},
    "version": "2.1.0",
    "route": ""
  }
]

Responses

200 Success

[
  {
    "events": ["EventName"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "a1f4c8e2-7b93-4d6a-9f2c-8e1d3b5a7c90",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "debounce_key": "listing-123456",
    "payload": {},
    "version": "2.1.0",
    "route": ""
  }
]

400 Invalid array of events

{
  "code": 400,
  "message": "Invalid request body, please check data: [0]: Key: 'RsbEvents.NodeID' Error:Field validation for 'NodeID' failed on the 'uuid4' tag"
}

400 Multiple node id

{
  "code": 400,
  "message": "Multiple node_id cannot be used in a single request."
}

400 No events

{
  "error": "no events",
}

400 No event names in request

{
  "error": "no events in request",
}

401 Unauthorized

{
  "code": 401,
  "message": "You are not authorized to use this resource."
}

413 Request body larger than 10MB

{
  "code": 413,
  "message": "Invalid request body, please check data: http: request body too large"
}

422 Invalid created_at datetime format

{
  "code": 422,
  "message": "created_at datetime is not a ISO8601/RFC3339 format"
}

503 Bus temporarily unavailable

{
  "code": 503,
  "message": "StatusServiceUnavailable: Bus is temporarily unavailable. Please queue events and re-submit at a later time."
}

503 Cannot feed event to broker

{
  "code": 503,
  "message": "Could not feed event to broker: invalid JSON: Please fix on consumer side"
}

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": "a1f4c8e2-7b93-4d6a-9f2c-8e1d3b5a7c90",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {
      "user": {}
    },
    "version": "2.1.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": "a1f4c8e2-7b93-4d6a-9f2c-8e1d3b5a7c90",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {},
    "version": "2.1.0"
  },
  {
    "events": ["Event2"],
    "from": "04f9f5d9-d84c-4636-acae-2067eee4d81f",
    "reference": "b2e5d9f3-8c04-5e7b-0a3d-9f2e4c6b8d01",	
    "created_at": "2022-05-09T16:59:14+02:00",
    "payload": {},
    "version": "2.1.0"
  },
]

Quick links

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