Web-API

Livebridge provides a simple Web-API endpoint for retrieving and/or saving of control data, as described here.

For using the Web-API following settings have to be set:

• LB_WEB_HOST - the host the server is listening on. 0.0.0.0 or 127.0.0.1 for example.
• LB_WEB_PORT - the port the server is listening on, 8080 for example.
• LB_WEB_USER - Username of the API user. Only a single user supported at the moment!
• LB_WEB_PWD - Password of the API user.

For more details about Web-API related configuration values, see here.

Endpoint

#scheme
https://[LB_WEB_HOST]:[LB_WEB_PORT]/api/v1/

# example
https://localhost:8080/api/v1/

Authentication

All requests require a HTTP-Header X-Auth-Token for authentication requests.

POST /api/v1/session

To retrieve this token for subsequent requests, /api/v1/session can be called, with the credentials defined in LB_WEB_USER and LB_WEB_PWD.

$ curl -XPOST -s -d "username=yourusername&password=yourpassword" \
http://localhost:8080/api/v1/session

The response returns a HTTP status 200 contains a JSON document with the token included:

{"token": "58725ad5-d669-4431-9991-1a0cff261526"}

This token is stored in memory by the API and will get invalid at restart and after re-requesting a new token.

Control bridges

[GET/PUT] /api/v1/controldata

This resource allows to retrieve and edit the controlling of livebridges. The data handled is JSON-formatted, independent from the used storage backend (file, s3, DBs).

Retrieving current control data

To get the current active control-data, a GET request on the resource returns the control data in JSON format, no parameters are required:

curl -XGET -s -H "X-Auth-Token: $TOKEN" \
-H "Content-Type: application/json" \
http://localhost:8080/api/v1/controldata

A successful request returns data with a HTTP status 200:

{
    "auth": {
        "live": {
            "user": "prod",
            "password": "pwd2",
            "api_key": "Foobar"
        }
    },
    "bridges": [{
        "endpoint": "https://example.com/api/",
        "label": "Example 1",
        "source_id": "abcdefg",
        "targets": [{
            "type": "another",
            "event_id": "654321",
            "auth": "live"
        }]
    }]
}

Putting new control data

With a PUT operation, initial control data can be saved or existing control data can be updated.

The request-payload is JSON-formatted and uploaded as request-body:

curl -XPUT -v -H "X-Auth-Token: $TOKEN" \
-H "Content-Type: application/json" \
-T control-api.json \
http://localhost:8080/api/v1/controldata

A successful PUT operation returns with a HTTP status 200 following:

{"ok": "true"}

If no control data exists, one can store initial control data this way.

Note

Running bridges are not restarted promptly after control data was updated. Instead the next periodically check for changed control data is awaited. The interval for these checks are defined by LB_POLL_CONTROL_INTERVAL.

Error responses

Error responses have the general, JSON-formatted form:

{"error": "Message"}

Following errors are possible:

HTTP	Error
400	Auth credentials are missing.
400	Controldata was not saved.
400	No request body was found.
401	Not authorized.
401	Invalid token.
401	Method Not Allowed
500	Internal Server Error