Nimbra Edge RESTful API #

Overview #

Nimbra Edge allows for programmatic access via a RESTful API.

This document describes how to get started with the API and provides a few command line examples.

Getting Started #

Open API Specification #

Each Nimbra Edge release includes a bundled OAS (Open API Specification) JSON document called edge-open-api-specification.json.

This document is a good starting point to get familiar with the Nimbra Edge HTTP API as it describes all the available endpoints, which endpoints require authentication, the details of the parameters required to invoke each endpoint, such as the HTTP method, HTTP headers, path, query and body parameters, etc.

It is possible to open the OAS document in a compatible OAS-viewer, for example Swagger.

Note: the OAS document uses OAS version 3.1.0, which Swagger UI supports from version 5.

Tips and Tricks #

To further understand the flow of network traffic, it is possible (in certain browsers, such as Google Chrome or Safari) to inspect the requests and responses performed by the Nimbra Edge web application (i.e. Network Manager). To do this:

  1. Open the web browser.
  2. Navigate to the web application by entering the url and pressing enter.
  3. Open the web browser developer tools (usually by right clicking and clicking on “Inspect”).
  4. Click on the “Network” tab.
  5. Click around in the web application and see which network requests are being performed.

Authentication #

Most endpoints require authentication details to be provided in the request. These are obtained by calling the POST /api/login/ endpoint, providing a username and password, and for accounts with multi-factor authentication the current one-time code in the otp field. If the login was successful a token is returned as the edgetoken cookie in the SET-COOKIE HTTP header of the response. Pass this token as a cookie in subsequent requests to endpoints which require authentication. Alternatively, pass an API token in the edge-api-token HTTP header.

Refer to the OAS document for information of which endpoints require authentication.

Unauthenticated requests will return 401 Unauthorized.

Ask the service provider to create a user account.

Authorization #

Different endpoints require different levels of authorization, i.e. the logged-in user may be required to have certain permissions, e.g. admin rights, in order to invoke a certain endpoint.

Ask the service provider to assign your user account with the appropriate authorization level.

Unauthorized requests will return 403 Forbidden.

Command line examples #

Prerequisites #

The following examples are performed in the terminal and use curl (https://curl.se/download.html) and jq (https://jqlang.org).

Log in # 

curl -X POST -H "Content-Type: application/json" -c cookieJar \
  -d '{"username":"<username>", "password":"<password>"}' \
  https://example.com/api/login/

A cookie containing an authentication token is returned from a successful login response and is stored in a file called “cookieJar”, using the “-c” flag. This file will be included in subsequent requests that require authentication, using the “-b” flag.

Get a list of all inputs # 

curl -b cookieJar "https://example.com/api/input/" | jq '.'

Get the details of a particular input #

The following example fetches the details of a specific input with id 6b252ee3-cb41-4bbf-a65d-e3c52fd4798e. The input id can be acquired from e.g. fetching the list of all inputs.

  1. Get the input.
INPUT_ID="6b252ee3-cb41-4bbf-a65d-e3c52fd4798e"
INPUT=$(curl -b cookieJar "https://example.com/api/input/${INPUT_ID}" | jq '.')
  1. Inspect its properties, e.g. its current health state.
echo "$INPUT" | jq '.health.state'

Get a list of all outputs # 

curl -b cookieJar "https://example.com/api/output/" | jq '.'

Get the details of a particular output #

The following example fetches the details of a specific output with id edbf7c0a-d7b5-49be-84d2-4eaedbc7c119. The output id can be acquired from e.g. fetching the list of all outputs.

  1. Get the output.
OUTPUT_ID="edbf7c0a-d7b5-49be-84d2-4eaedbc7c119"
OUTPUT=$(curl -b cookieJar "https://example.com/api/output/${OUTPUT_ID}" | jq '.')
  1. Inspect its properties, e.g. its current health state.
echo "$OUTPUT" | jq '.health.state'

Send an input to an output #

The following example assigns the input with id 6b252ee3-cb41-4bbf-a65d-e3c52fd4798e to the output with id edbf7c0a-d7b5-49be-84d2-4eaedbc7c119. The input id can be acquired from e.g. fetching the list of all inputs. The output id can be acquired from e.g. fetching the list of all outputs.

curl -X PUT -H "Content-Type:application/json" -b cookieJar -d "{\"input\":\"${INPUT_ID}\"}" \
  "https://example.com/api/output/${OUTPUT_ID}/input"

Disable an output #

The following example disables an output by setting the adminStatus of the output to 0 (off). The output id can be acquired from e.g. fetching the list of all outputs.

  1. Get the output.
OUTPUT=$(curl -b cookieJar "https://example.com/api/output/${OUTPUT_ID}")
  1. Update locally: Set the adminStatus property of the output to 0.
UPDATED_OUTPUT=$(echo "$OUTPUT" | jq '.adminStatus = 0')
  1. Update remotely: Pass the updated output to the Nimbra Edge API.
curl -X POST -H "Content-Type:application/json" -b cookieJar -d "$UPDATED_OUTPUT" \
  "https://example.com/api/output/${OUTPUT_ID}"

Get a list of all appliances # 

curl -b cookieJar "https://example.com/api/appliance/" | jq '.'

Get a filtered list of the 10 first appliances containing the string “default” in their name #

The following example provides a URL encoded filter as a query parameter to the “list appliances” endpoint.

The filter to url-encode: {"filter":{"searchName":"default"},"skip":0,"limit":10}

QUERY=$(echo -n '{"filter":{"searchName":"default"},"skip":0,"limit":10}' | jq -sRr @uri)
curl -b cookieJar "https://example.com/api/appliance/?q=${QUERY}" | jq '.'

Get the details of a particular appliance #

The following example fetches the details of a specific appliance with id 92e7823c-38ef-4e8f-8664-7c1f2c174096 and then inspects its health state.

The appliance id can be acquired from e.g. fetching the list of all appliances.

  1. Get the appliance.
APPLIANCE_ID="92e7823c-38ef-4e8f-8664-7c1f2c174096"
APPLIANCE=$(curl -b cookieJar "https://example.com/api/appliance/${APPLIANCE_ID}" | jq '.')
  1. Inspect the appliance health state.
echo "$APPLIANCE" | jq '.health.state'

Check the software version # 

curl "https://example.com/api/build-info" | jq '.'

No authentication is required.

Output Status Codes #

When querying output metrics, the status field of the udpOutput entries in metrics.ristMetrics[] indicates the current state of the output. The following status codes may be returned:

Status Description
playing Output is playing normally.
no_data No data is being played because no data is available.
no_origin_time¹² No origin timestamps are received. No data is being played.
no_common_time_base¹² Source node and playout node do not share a common clock. It is possible, but not guaranteed, that data is played, just not at the desired time.
lagging¹ Data cannot be played at the intended time. It is possible, but not guaranteed, that data is played.

¹ Applies only to outputs in delayMode 2 (basedOnOriginTime).

² Status may linger after input is stopped.

Understanding the lagging status #

The lagging status can indicate one of the following conditions: