Xbus recipient API

Description of the API Xbus recipients must implement in order to register into an Xbus network.

Version of this document: 0.2.

Methods described in this document:

Workflows

Recipients can receive multiple events concurently, the only constraint is that the broker cannot send start_event to a recipient until it is “ready”.

digraph recipient { rankdir=LR; node [shape = circle] start; node [shape = circle] ready; node [shape = circle] processing; start -> ready [label = "sends ready"]; ready -> processing [label = "receives start_event"]; processing -> ready [label = "sends ready"] }

Events corresponding to a particular envelope are sequential. There is no start_envelope event, the recipient is expected to infer the begining of envelopes with the envelope IDs passed in each event.

digraph recipient_message_life_cycle { rankdir=LR node [shape = circle] start; node [shape = circle] wait_event; node [shape = circle] in_event; node [shape = circle] stop; start -> in_event [label = "start_event"]; in_event -> wait_event [label = "end_event"]; in_event -> stop [label = "stop_envelope"]; wait_event -> in_event [label = "start_event"]; wait_event -> stop [label = "end_envelope"]; wait_event -> stop [label = "stop_envelope"]; }

get_metadata

get_metadata()

Required.

Called to ask for information about the recipient.

Return type:dict
Returns:A dictionary.

Required return dictionary keys:

  • name (string): Name of the recipient.
  • version (float): Version of the recipient.
  • api_version (float): Version of the Xbus recipient API.
  • host (string): Host name of the server hosting the recipient.
  • start_date (string): ISO 8601 date-time of When the recipient was started.
  • local_time (string): ISO 8601 time on the recipient server.

Optional return dictionary keys:

ping

ping(token)

Required.

Called when Xbus wants to check whether the recipient is up.

Parameters:token (str) – String that must be sent back.
Returns:The token string sent as parameter.

has_clearing

has_clearing()

Required.

Called to determine whether the recipient supports the “data clearing” feature; and if it does, to get more information about that process.

Returns:2-element tuple:
  • Boolean indicating whether the feature is supported.
  • URL of the data clearing database (or nothing if the feature is not supported). The database must respect the schema described in the “Data clearing” section of the Xbus documentation.

has_immediate_reply

has_immediate_reply()

Required.

Called to determine whether the recipient supports the “immediate reply” feature.

Returns:2-element tuple:
  • Boolean indicating whether the feature is supported.
  • List of event type names the recipient declares immediate reply support for.

start_event

start_event(envelope_id, event_id, type_name)

Required.

Called when a new event is available.

Parameters:
  • envelope_id (str) – [TODO] String.
  • event_id (str) – [TODO] String.
  • type_name (str) – [TODO] String.
Returns:

[TODO] tuple.

send_item

send_item(envelope_id, event_id, indices, data)

Required.

Called to send the recipient an item.

Parameters:
  • envelope_id (str) – [TODO] String.
  • event_id (str) – [TODO] String.
  • index (int) – index of the item in the event.
  • data – [TODO] Byte array.
Returns:

[TODO] tuple.

end_event

end_event(envelope_id, event_id)

Required.

Called at the end of an event.

Parameters:
  • envelope_id (str) – [TODO] String.
  • event_id (str) – [TODO] String.
Returns:

[TODO] tuple.

end_envelope

end_envelope(envelope_id)

Required.

Called once an envelope (and its individual events) has been sent.

Parameters:envelope_id (str) – [TODO] String.
Returns:[TODO] tuple.

stop_envelope

stop_envelope(envelope_id)

Required.

Called to signal an early envelope exit.

Parameters:envelope_id (str) – [TODO] String.
Returns:[TODO] boolean.