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 :ref:`http-setup-accounts`.

Emission
--------

.. http: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**:

    .. sourcecode:: http

        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**:

    .. sourcecode:: http

        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.

.. http:get:: /(actor_id)/processrequest

    Returns the next ActorProcessRequest for this actor

    **Example request**:

    .. sourcecode:: http

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

    **Example response**:

    .. sourcecode:: http

        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
                    }]
                }
            }]
        }


.. http: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**:

    .. sourcecode:: http

        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"
            }]
        }