Xbus connector API¶
This section describes the API exposed by the Xbus server to various connectors.
This document corresponds to Xbus 3.0.0.
General concepts¶
Connectivity¶
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 secure through TLS.
Data format¶
All data transiting through Xbus is to be JSON serialized.
In the near future, JSON Schema is planned here.
Data encryption¶
The data needs no encryption since TLS connections already provide that.
Serialized objects¶
Several objects are re-used to compose communication messages. They are JSON serialized.
Actor¶
Actors connect to Xbus to send or receive messages. They rely on an account to handle their authentication.
id
: String. A UUID.name
: String.kind
: String. One of:emitter
.worker
.consumer
.
status
: String. One of:pending
.enabled
.disabled
.rejected
.
account_id
: String. A UUID.roles
: List of strings.visible
: Boolean.last_seen
: Date & time, such as0001-01-01T00:00:00Z
.
Envelope¶
An envelope transits through Xbus to deliver one or multiple messages.
id
: String. A UUID.event_ids
: List of UUID strings. If provided, the complete list of event IDs of the envelope. Will be used to make sure all the pieces were properly received.events
: List of event objects.last
: Boolean. True if this is the last envelope of a streamed envelope or a unique envelope.context
: Object with:process_id
: String. A UUID.node_id
: String.
The context contains information used by the server to track the graph execution. It should be considered a blackbox from the worker point of view, which only copies it from input envelopes to output envelopes.
An actor must copy this value from input envelopes to output envelopes.
Emitters must not set this value.
Event¶
An event represents a message. It is the base unit manipulated by the graph.
id
: String. A UUID.type
: String.index
: Integer.items
: List of JSON serialized data.count
: Integer. The amount of items this event contains.checksum
: Integer.
Response¶
Responses all include the following fields:
status
: Integer. One of:1
: OK.2
: Server error.3
: Error due to the client input.
status_message
: String.
Response (envelope)¶
Responses to envelope messages contain response fields, plus:
id
: String. A UUID.reception_status
: String. 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.
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.
xbus.registration
:name
: String.type
: String. One of:actor
.user
.
csr
: String. PEM-encoded PKCS #10 Certificate Signing Request.actors
: List of actor objects.
Response to
xbus.registration
:
Message emission¶
This section details the API involved in sending messages to the server from an emitter.
Message consumption¶
This section details APIs involved in consuming messages sent by servers to recipients (workers / consumers).
Recipients receive messages via envelope objects onto the
xbus.msgbox.<actor-ID>.input.default
subject (where<actor-ID>
is the ID of the actor created for the emitter); recipients therefore have to subscribe to that subject should they want to receive messages.Recipients should subscribe with the option of letting the server provide the reply subject, so they can send replies on that subject.
Recipients publish a reception_envelope object for each emission to the reply subject received above. The
registration_status
field of that object should be set toaccepted
.