API

Authentication

To be recognized by the HTTP gateway, a HTTP header “Xbus-API-Key” must be added to every request.

To get a API key, see Configuring accounts.

Emission

POST /(actor_id)/output`

Emit a complete envelope to a actor output. The payload is a json-encoded xbus.OutputRequest (see xbus-api).

Example request:

POST /emitter1/output HTTP/1.1
Host: example.com
Accept: application/json
Accept-Item-Encoding: binary
Content-Type: application/json
Xbus-API-Key: MyClientAccountAPIKey

{
    "output": "default",
    "envelope": {
        "event_ids": ["53131466-4e2e-11e7-916e-af2b1e6d242d"],
        "events": [{
            "id": "53131466-4e2e-11e7-916e-af2b1e6d242d",
            "type": "test",
            "ItemCount": 1,
            "encoding": "binary",
            "items": ["QSBtZXNzYWdl"]
        }]
    }
}

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

OK

Process

This method, while being simple, is less reliable than using webhooks. Unless your client cannot implement a webhook endpoint, this method is not recommanded.

GET /(actor_id)/processrequest

Returns the next ActorProcessRequest for this actor

Example request:

GET /emitter1/processrequest HTTP/1.1
Host: example.com
Accept: application/json
Accept-Item-Encoding: json,binary
Xbus-API-Key: MyClientAccountAPIKey

Example response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
    "context": {},
    "inputs": [{
        "name": "default",
        "envelope": {
            "event_ids": ["53131466-4e2e-11e7-916e-af2b1e6d242d"],
            "events": [{
                "id": "53131466-4e2e-11e7-916e-af2b1e6d242d",
                "type": "test",
                "ItemCount": 1,
                "encoding": "binary",
                "items": ["QSBtZXNzYWdl"]
            }]
        },
        "envelopeposition": {
            "envelope_id": "53131466-4e2e-11e7-916e-af2b1e6d242d",
            "start": true,
            "complete": true,
            "eventPosisions": [{
                "event_id": "53131466-4e2e-11e7-916e-af2b1e6d242d",
                "index": 1,
                "itemCount": 1
            }]
        }
    }]
}

POST /(actor_id)/processingend

Signal end of processing by the actor. Must be called for every request retrieved. The payload is a json-encoded ActorProcessingState (see xbus-api).

Example request:

POST /emitter1/processingend HTTP/1.1
Host: example.com
Accept: application/json
Accept-Item-Encoding: binary
Content-Type: application/json
Xbus-API-Key: MyClientAccountAPIKey

{
    "context": {},
    "status": "SUCCESS",
    "messages": [{
        "timestamp": "2018-08-20T22:56:12Z",
        "level": "NOTICE",
        "text": "Hello there"
    }]
}