REST API

A curated subset of the Ursa Studio REST API is documented via the Open API Specification. Users can navigate to the generated documentation for the REST API via a link in the Integration Manager.

Version 1 API

Nearly all of the interactions between the browser and the server in Ursa Studio work via an existing REST API that is implemented on the server. A subset of these endpoints have been documented via the Open API Specification, and these represent the stable version-1 surface area upon which customers can build their own solutions. Pre-existing (version-0) endpoints are documented and conformed to the version-1 standard as the need arises.

Endpoints

The most current documentation of the version 1 REST API can be found on the api-docs screen, as linked to from the Integration Manager. This screen also allows users to interactively test the server with real-life requests and responses.

Triggering ELTs

Customers can use the integration-manager REST endpoints to integrate Ursa ELTs into their own workflow without the need to log in to Ursa Studio. 

The trigger-elt endpoint kicks off a saved ELT, and returns the eltID of that particular ELT run. By polling the elt-status endpoint with this eltID, the invoking function can know when the ELT is complete so as to kick off the next step of the workflow. 

These two endpoints allow authentication via an URSA_REST_API_TOKEN as an alternative to the typical session authentication used by the other REST endpoints. You can contact your Ursa Health team for your token for Ursa Cloud and Hybrid Cloud deployments.

Sample code for Python and NodeJS is as follows:

import requests
import os
import time
from urllib.parse import urlencode

# Initial setup
host = "https://your.ursastudio.url"
api_token = os.getenv("URSA_REST_API_TOKEN")
saved_elt_name = "My Saved ELT"

# Trigger ELT
trigger_elt_endpoint = f"{host}/api/v1/integration-manager/trigger-elt"
trigger_data = {
    "savedEltName": saved_elt_name,
    "apiToken": api_token
}
trigger_response = requests.post(trigger_elt_endpoint, json=trigger_data)
trigger_response_data = trigger_response.json()
elt_id = trigger_response_data["eltID"]

# Check status 
status_endpoint = f"{host}/api/v1/integration-manager/elt-status"
status_params = {
    "savedEltName": saved_elt_name,
    "apiToken": api_token,
    "eltID": elt_id
}

def check_status():
    response = requests.get(status_endpoint + "?" + urlencode(status_params))
    if response.status_code != 200:
        print(response.text)
        return False
    response_data = response.json()
    if response_data.get("status") == "COMPLETE":
        print("Build is complete")
        return True
    return False

interval = 60
while True:
    if check_status():
        break
    time.sleep(interval)

const request = require("superagent");
const qs = require("qs");
const agent = request.agent();
const host = "https://your.ursastudio.url";
const savedEltName = "My Saved ELT";

agent
  .post(`${host}/api/v1/integration-manager/trigger-elt`)
  .send({
    savedEltName,
    apiToken: process.env.URSA_REST_API_TOKEN
  })
  .end((triggerErr, triggerResponse) => {
    const eltID = triggerResponse.body.eltID;
    const statusParams = {
      savedEltName,
      apiToken: process.env.URSA_REST_API_TOKEN,
      eltID
    };
    const intervalID = setInterval(() => {
      agent
        .get(`${host}/api/v1/integration-manager/elt-status?${qs.stringify(statusParams)}`)
        .end((err, response) => {
          if (err) {
            console.log(err.message);
            return;
          }
          if (response.body?.status === "COMPLETE") {
            clearInterval(intervalID);
            console.log("Build is complete");
          }
        });
    }, 60000);
  });