Xbus connector API

This section describes the API exposed by the Xbus server to various connectors.


This documentation is deprecated and will be removed soon. The API is now automatically documented, see Xbus API.

General concepts


Connectors all connect to the Xbus server to communicate; they do not need to connect between each other. The Xbus server is in charge of propagating messages from one connector to the other.

Connections are standard NATS connections secure through TLS.

Data format

All data transiting through Xbus is to be JSON serialized.

In the near future, JSON Schema is planned here.

Error management

See the response object for generalities and detailed information below for specifics when applicable.

Serialized objects

Several objects are re-used to compose communication messages. They are JSON serialized.



Envelope context is a blackbox object that must be copied from incoming envelopes to outcoming envelopes.

Although its internal structure is not part of the API, here it is:

process_id UUID
ID of the process in which the envelope is being manipulated
node_id string
The pipeline node corresponding to the actor

An envelope transits through Xbus to deliver one or multiple messages. Can be a fragment of a bigger envelope.

Aside from its “context” attribute, an envelope is immutable.

Unique ID of the envelope

event_ids [UUID]

If provided, the complete list of event IDs of the envelope. Will be used to make sure all the pieces were properly received.

events [Event]

last Boolean

True if this is a whole envelope or the last fragment of a splitted envelope
context Context

A worker must copy this value from input envelopes to output envelopes.

Emitters must not set this value.


An event represents a message. It is the base unit manipulated by the pipeline.


type String

index Integer
Index of the event fragment in a splitted event

items [String]

count Integer
The amount of items this event contains.
checksum Integer
A CRC32 sum of the event

Data types


Actors connect to Xbus to send or receive messages. They rely on an account to handle their authentication. Here is the “Actor” structure that describes an actor:

The unique ID of the actor
name String
The unique name of the actor
kind String

Kind of the actor. Can be one of:

  • emitter.
  • worker.
  • consumer.
status String

Current status of the actor. Can be one of:

  • pending.
  • enabled.
  • disabled.
  • rejected.
account_id UUID
Account to which the actor is attached
roles [String]
Roles affected to the actor
visible Boolean
True when the actor is currently visible on the bus
last_seen Iso-encoded date & time string
Last moment where the actor has been seen.



Message sent to the Xbus logging system.

time ISO-8601 date string

level String

Must be one of:

  • notice.
  • warning.
  • error.

text String



Base type for all responses types.

status String

Status of the response. One of:

  • OK
  • ServerError
  • ClientError: Error due to the client input.
status_message String
A message explaining why the status is not “OK” (if applicable)

Responses to envelope messages contain Response fields, plus:

ID of the envelope
reception_status String

Indicates the reception status of the envelope. One of:

  • receiving: The envelope is still incomplete and the receiver is waiting for the remaining parts.
  • accepted: The envelope has been completely received and is guaranteed to be processed.
  • error: An error occured during the reception of immediate processing of the envelope.
reason String
A message explaining why the reception_status is error

Account / actor registration

This section details the API involved in registering an account (and if necessary, an actor) allowed to communicate with Xbus.

It should be noted that all of this may be automated by running the xbus-client program.

This API is the only one accessible by unregistered accounts.

name String
Name of the account
type String

Type of the account. One of:

  • actor.
  • user.
  • gateway.
csr String
PEM-encoded PKCS #10 Certificate Signing Request.
actors [actor]
All the actors attached to the account.

Inherits Response

registration_status String

One of:

  • pending The registration needs to be accepted by an administrator
  • accepted The registration was accepted by an administrator, the account certificate can now be used to authenticate.
  • rejected The registration was rejected by an administrator.
Unique ID of the account. Generated by the server on the first registration attempt.
signed_certificate String
PEM-encoded X.509 certificate.
server_ca String
PEM-encoded X.509 certificate.
actors [Actor]
Updated list of actors attached to the account. The

Message emission

This section details the API involved in sending messages to the server from an emitter.

Normal envelope

xbus.msgbox.<actor-ID>.output.default, where <actor-ID> is the unique ID of the emitter

A Envelope object

Can be a complete or a fragment of an envelope.

A EnvelopeAck object

The emitter should ensure the registration_status field of that object is not set to error.

Closing output

In some case no envelope will ever be sent to a output, so the actor can explicitely close the output (or use ProcessingEnd).

This is done by sending a special envelope:

Close output envelope

context EnvelopeContext

last Bool
Must be set to True

Forward envelope

If a worker needs to send the same envelope it received on an input, it must send a special envelope:

Forward Envelope
The ID of the envelope to forward

context EnvelopeContext

last Bool
Must be set to True

Message consumption

This section details APIs involved in consuming messages sent by servers to recipients (workers / consumers).


Listen subjects
Initial fragment

xbus.msgbox.<actor-ID>.input.<inputname>, where <actor-ID> is the ID of the consumer, and <inputname> the name of the input.

Currently only a “default” input should be used.

Remaining fragments
xbus.msgbox.<actor-ID>.input.<inputname>.<envelope_id>, where <actor-ID> is the ID of the consumer, <inputname> the name of the input. and <envelope_id> is the id of the envelope.
Incoming message
A Envelope
A EnvelopeAck <xbus_api_envelope_ack>`

Once an envelope is successfully received, a consumer must call the ProcessingEnd API.


Used by recipients (workers / consumers) to tell Xbus whether they could successfully process data, if and only if not all their output were closed.

Mandatory for consumers.

If a worker use this API, all the output on which no envelope was sent will be automatically closed.

xbus.actor.<actor-ID>.processingend, where <actor-ID> is the ID of the actor.


envelope_id UUID
The envelope that was processed

context EnvelopeContext

result String

Final state of the processing. Must be one of:

  • success.
  • error.
messages [LogMessage]
When result is error, and only in that case, a list of log messages that may justify the error.
A Response