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.

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.

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 as 0001-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:

    • registration_status: String. One of:

      • pending.
      • accepted.
      • rejected.
    • id: String. A UUID.

    • signed_certificate: String. PEM-encoded X.509 certificate.

    • server_ca: String. PEM-encoded X.509 certificate.

    • actors: List of actor objects.

    • And usual response fields.

Message emission

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

  • Messages are all sent via envelope objects to the xbus.msgbox.<actor-ID>.output.default subject (where <actor-ID> is the ID of the actor created for the emitter).
  • The response is a reception_envelope object. The emitter should ensure the registration_status field of that object is not set to error.

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 to accepted.