Quickstart Guide

Learn how to use API keys to make programmatic requests to the Compute Engine.

This guide will show you how to get started and run your first task on the Signaloid Cloud Developer Platform via the Signaloid Cloud Compute Engine API. In this guide, you will build a simple application that authenticates with the Signaloid Cloud Compute Engine API and runs a Source Code task on a custom C0 Cloud Processor Core that was also provisioned via the API.

Before you start

You will learn:

How to create API keys to programmatically access the Signaloid Cloud Compute Engine.
How to create Signaloid C0 cores via the API.
How to launch a new Build via the API.
How to retrieve Build outputs from the API.
How to launch a new Task via the API.
How to retrieve Task outputs from the API.

You will need:

A Signaloid Cloud account. You can create an account for free at get.signaloid.io.

caution

For brevity, the code examples below do not include error handling code. They present the bare minimum required to get you started with using the Compute Engine API.

Note

The Free and Developer tiers allow you to create and use API keys but have a very limited API access quota. You need a Developer+API tier or Enterprise tier subscription to use the Signaloid API effectively. You can upgrade your subscription on the Billing page of the Signaloid Cloud Developer Platform.

Authenticating with the Signaloid Cloud Compute Engine API

API key authentication

Once you have created a Signaloid Cloud account, log-in to the Signaloid Cloud Developer Platform and go to the settings page. Create a new API key and make a note of it.

caution

For security reasons, you will not be able to view the api key again. If you forget the API key you would need to create a new api key and update your applications to use the new key.

cURL
TypeScript

If you are making requests using cURL, you need to make sure you set the Authorization header with your api key with every request you make to the Signaloid Cloud Compute Engine API.

# API token generated from signaloid.io/settings/api
SIGNALOID_API_KEY="scce_yourSignaloidCloudApiKey"

The code snippet below shows how to set the header with the api key when making a request to the /tasks endpoint.

curl --location "https://api.signaloid.io/tasks/" --header "Authorization: $SIGNALOID_API_KEY"

# or

curl --location "https://api.signaloid.io/tasks/" --header "Authorization: scce_yourSignaloidCloudApiKey"

// API token generated from signaloid.io/settings/api
const apiToken =  process.env.SIGNALOID_KEY || "scce_yourSignaloidCloudApiKey";
const baseURL =  process.env.SIGNALOID_URL || "https://api.signaloid.io";

// Setup HTTP client
const axios = require("axios");
const signaloidClient = axios.create({
  baseURL: baseURL,
});

// Setup request headers
signaloidClient.defaults.headers["Authorization"] = `${apiToken}`;
signaloidClient.defaults.headers["Content-Type"] = "application/json";

The code snippet above creates an HTTP client using the Axios library, and sets the API key you generated to its default Headers list to authenticate all the requests made to the Signaloid Cloud Compute Engine API using that client. Please refer to the Axios documentation for more details.

Select a Core

Every task on the Signaloid Cloud Compute Engine runs on an Execution Core. Your Signaloid Cloud account gives you access to a set of default execution cores. In this guide we will use the default C0-S+ core to run our compute tasks. Please refer to the Cores documentation for more details on the default cores and how to create custom execution cores.

The default C0-S+ core has the core ID cor_b21e4de9927158c1a5b603c2affb8a09. We will use this ID when creating a task with the Signaloid Cloud Compute Engine API to run it on the C0-S+ core.

cURL
TypeScript

# Core ID of the C0-S+ core
SIGNALOID_CORE_ID="cor_b21e4de9927158c1a5b603c2affb8a09"

// Core ID of the C0-S+ core
const coreID = "cor_b21e4de9927158c1a5b603c2affb8a09";

## Make a Build request

Now that you have the ID of an Execution Core, you can use the API to run applications on it. In this example we will be trying to build the following simple c program on the Signaloid Cloud Compute Engine.

#include <stdio.h>
int main() {
  printf("Hello World");
  return 0;
}

You can refer to the usage guides for more complex application examples. Building code on the Signaloid Cloud Compute Engine via the Signaloid Cloud Compute Engine API involves four (4) steps:

Creating the source code build request object
Submitting the build object to obtain a BuildID
Using the BuildID to fetch the build status
Using the BuildID to fetch the build log if build has failed

Create a `SourceCode` task request

cURL
TypeScript

The code below shows the complete build request object:

BUILD_OBJECT='{
      "Code": "#include <stdio.h>\n int main() {   printf(\"Hello World\");   return 0; }",
      "Language": "C",
      "CoreID": "'$SIGNALOID_CORE_ID'",
    }'

The code snippet below show the TypeScript interfaces the code execution task request object should adhere to.

type SourceCodeBuildRequest = {
  Code: string;
  Language: "C" | "C++" | "Fortran";
  // Optional
  CoreID?: string; // Using lowest precision C0 Athens core if not specified
  TraceVariables?: TraceVariableRequest[]; // Used to trace variables on Reference core runs
  DataSources?: DataSource[]; // Setting optional default data source for tasks started from this build
  Arguments?: string; // Setting optional default arguments for tasks started from this build
};

type DataSource = {
  ResourceID: string;
  ResourceType: "Gateway" | "Bucket" | "SignaloidCloudStorage";
  Location: string;
};

type TraceVariableRequest = {
  File: string;
  LineNumber: number;
  Expression: string;
};

Note

The TypeScript type definitions above have been truncated to only show what is relevant for code build. Please refer to the API reference for detailed configuration of the execution job request.

The code below shows the complete build request object:

const codeToBeRun = `
#include <stdio.h>
int main() {
  printf("Hello World");
  return 0;
}
`;
    
const buildRequest: SourceCodeBuildRequest = {
    Code: codeToBeRun,
    Language: "C",
    CoreID: coreID,
};
  

Submit the Build request

Once the buildRequest object is initialised, you can make a POST request to /sourcecode/builds.

cURL
TypeScript

curl --location 'https://api.signaloid.io/sourcecode/builds' \
  --header "Content-Type: application/json" \
  --header "Authorization: $SIGNALOID_API_KEY" \
  --data "$BUILD_OBJECT"

The code below shows the same request as a "one-liner" without using the variables:

curl --location 'https://api.signaloid.io/sourcecode/builds' \
  --header "Content-Type: application/json" \
  --header "Authorization: scce_yourSignaloidCloudApiKey" \
  --data '{
      "Code": "#include <stdio.h>\n int main() {   printf(\"Hello World\");   return 0; }",
      "Language": "C",
      "Core": "cor_b21e4de9927158c1a5b603c2affb8a09"
  }
'

console.log("Submitting the build to the API...");
let buildPostResponse;
try {
  buildPostResponse = await signaloidClient.post("/sourcecode/builds", buildRequest);
  if (buildPostResponse.data.BuildID) {
    console.log(`...build successfully created with ID: ${buildPostResponse.data.BuildID}`);
  }
  /*
   * response.data will contain the execution job response object
   */
} catch (error) {
  console.error(error);
}

If the Signaloid Cloud Compute Engine accepts the build request, you should get a 202:Accepted response. If not please refer to the API reference to diagnose the error. The code snippet below shows what the response from the API would look like if the execution job was successfully created.

{
  "data": {
    "BuildID": "bld_6dcae4d1c4f585901efa12a89a063996",
  },
  "status": 202,
  "statusText": "Accepted",
  [...other response keys omitted]
}

You can now use the BuildID to query the status of the build and get the results of the execution!

Fetch the Build's status

With the BuildID, you can make a GET request to /builds/{BuildID} to query the status of the task. The Status key will reflect the current status of the task. The build can be in the following statuses: Accepted, Initialising, Building, In Progress, Completed, Rescheduled, Cancelled, or Stopped. Until the task reaches a terminal state, you should poll the /tasks/{TaskID} endpoint. The code below polls the build status endpoint every 2 seconds.

cURL
TypeScript

# Build ID returned by the API when you created the build
BUILD_ID="bld_6dcae4d1c4f585901efa12a89a063996"

curl --location "https://api.signaloid.io/builds/$BUILD_ID" \
  --header "Authorization: $SIGNALOID_API_KEY"

let buildID = buildPostResponse.data.BuildID;
let buildStatus = "Accepted";

const delay = (ms:number) => new Promise((res) => setTimeout(res, ms));
console.log("Waiting for the task to finish...");
while (![`Completed`, `Cancelled`, `Stopped`].includes(buildStatus)) {
  await delay(2000);
  try {
    const buildGetResponse = await signaloidClient.get(`/builds/${buildID}`);
    buildStatus = buildGetResponse.data.Status;
    if (buildPostResponse.data.BuildID) {
      console.log(`...build status : ${buildStatus}`);
    }
    /*
     * response.data will contain the task details
     */
  } catch (error) {
    console.error(error);
  }
}

console.log(`Build in terminal state : ${buildStatus}.`);  

Please refer to the guide on running Source Code Tasks for a more comprehensive guide on how to poll the build status endpoint.

Note

Currently the build status endpoint only supports getting status via short polling. In future versions of the API, we will add support for other persistent connection mechanisms.

Retrieve the Builds's outputs

Once the build is in a terminal state (Completed, Cancelled, or Stopped), you can retrieve the outputs of the build from the API by making a GET request to builds/{buildID}/outputs.

cURL
TypeScript

# Build ID returned by the API when you created the build
BUILD_ID="bld_6dcae4d1c4f585901efa12a89a063996"

curl --location "https://api.signaloid.io/builds/$BUILD_ID/outputs" \
  --header "Authorization: $SIGNALOID_API_KEY"

console.log("Fetching build outputs...");
let buildOutputsResponse;
try {
  // get task data from API
  buildOutputsResponse = await signaloidClient.get(`/builds/${buildID}/outputs`);
  /*
   * response.data will contain the task outputs object
   */
  if (buildOutputsResponse.data.Build) {
    const outputStream = await axios.get(buildOutputsResponse.data.Build);
    console.log(`Build log: ${outputStream.data}`);
  }
} catch (error) {
  // [TODO]: handle errors
}

The response will have the following shape:

{
  "data": {
    "Build": "..."
  },
  "status": 200,
  "statusText": "Ok"
}

Build key of this object will be a URL to the file containing the output of the build from corresponding output stream. The build stream contains the build output of the application. The streams may not be available for builds that failed.

Make a Task execution request

Now that you have the ID of an Build, you can use the API to run applications on it. We will be trying to run the previous simple c program on the Signaloid Cloud Compute Engine.

You can refer to the usage guides for more complex application examples. Running code on the Signaloid Cloud Compute Engine via the Signaloid Cloud Compute Engine API involves four (4) steps:

Submitting the build for execution to obtain a TaskID
Using the TaskID to fetch the task status
Using the TaskID to fetch the task results if task has completed

Submit the Task request

You can make a POST request to builds/{BuildID}/tasks.

cURL
TypeScript

BUILD_ID="bld_6dcae4d1c4f585901efa12a89a063996"

curl --location "https://api.signaloid.io/builds/$BUILD_ID/tasks" \
  --header "Authorization: $SIGNALOID_API_KEY"

console.log("Submitting the task to the API...");
let taskPostResponse;
try {
  taskPostResponse = await signaloidClient.post(`builds/${buildID}/tasks`);
  if (taskPostResponse.data.TaskID) {
    console.log(`...task successfully created with ID: ${taskPostResponse.data.TaskID}`);
  }
  /*
   * response.data will contain the execution job response object
   */
} catch (error) {
  console.error(error);
}

If the Signaloid Cloud Compute Engine accepts the task request, you should get a 202:Accepted response. If not please refer to the API reference to diagnose the error. The code snippet below shows what the response from the API would look like if the execution job was successfully created.

{
  "data": {
    "TaskID": "tsk_6dcae4d1c4f585901efa12a89a063996",
  },
  "status": 202,
  "statusText": "Accepted",
  [...other response keys omitted]
}

You can now use the TaskID to query the status of the task and get the results of the execution!

Fetch the Task's status

With the TaskID, you can make a GET request to /tasks/{TaskID} to query the status of the task. The structure of the response from this endpoint will be similar to the response you got when you submitted the task request. The Status key will reflect the current status of the task. The task can be in the following statuses: Accepted, Initialising, Building, In Progress, Completed, Rescheduled, Cancelled, or Stopped. Until the task reaches a terminal state, you should poll the /tasks/{TaskID} endpoint. The code below polls the task status endpoint every 2 seconds.

cURL
TypeScript

# Task ID returned by the API when you created the task
TASK_ID="tsk_6dcae4d1c4f585901efa12a89a063996"

curl --location "https://api.signaloid.io/tasks/$TASK_ID" \
  --header "Authorization: $SIGNALOID_API_KEY"

let taskID = taskPostResponse.data.TaskID;
let taskStatus = taskPostResponse.data.Status;
  
console.log("Waiting for the task to finish...");
while (![`Completed`, `Cancelled`, `Stopped`].includes(taskStatus)) {
  await delay(2000);
  try {
    const taskGetResponse = await signaloidClient.get(`/tasks/${taskID}`);
    taskStatus = taskGetResponse.data.Status;
    if (taskPostResponse.data.TaskID) {
      console.log(`...task status : ${taskStatus}`);
    }
    /*
     * response.data will contain the task details
     */
  } catch (error) {
    console.error(error);
  }
}
  
console.log(`Task in terminal state : ${taskStatus}.`);

Please refer to the guide on running Source Code Tasks for a more comprehensive guide on how to poll the task status endpoint.

Note

Currently the task status endpoint only supports getting status via short polling. In future versions of the API, we will add support for other persistent connection mechanisms.

Retrieve the Task's outputs

Once the task is in a terminal state (Completed, Cancelled, or Stopped), you can retrieve the outputs of the task from the API by making a GET request to tasks/{taskID}/outputs.

cURL
TypeScript

# Task ID returned by the API when you created the task
TASK_ID="tsk_6dcae4d1c4f585901efa12a89a063996"

curl --location "https://api.signaloid.io/tasks/$TASK_ID/outputs" \
  --header "Authorization: $SIGNALOID_API_KEY"

console.log("Fetching task outputs...");
let taskOutputsResponse;
try {
  // get task data from API
  taskOutputsResponse = await signaloidClient.get(`/tasks/${taskID}/outputs`);
  /*
   * response.data will contain the task outputs object
   */
  if (taskOutputsResponse.data.Stdout) {
    const outputStreamStdout = await axios.get(taskOutputsResponse.data.Stdout);
    console.log(`Task Stdout: ${outputStreamStdout.data}`);
  }
  if (taskOutputsResponse.data.Stderr) {
    const outputStreamStderr = await axios.get(taskOutputsResponse.data.Stderr);
    console.log(`Task Stderr: ${outputStreamStderr.data}`);
  }
} catch (error) {
  console.error(error);
}

The response will have the following shape:

{
  "data": {
    "Stdout": "...",
    "Stderr": "...",
  },
  "status": 200,
  "statusText": "Ok"
}

Each key of this object will be a URL to the file containing the output of the task from corresponding output stream. The build stream contains the build output of the application. The stdout and stderr streams will not be available for tasks that failed to build. If the task completed successfully, the file containing the output of the stdout stream will contain the following text:

Hello World

Quickstart Guide

Learn how to use API keys to make programmatic requests to the Compute Engine.

Before you start​

Authenticating with the Signaloid Cloud Compute Engine API​

API key authentication​

Select a Core​

Create a SourceCode task request​

Submit the Build request​

Fetch the Build's status​

Retrieve the Builds's outputs​

Make a Task execution request​

Submit the Task request​

Fetch the Task's status​

Retrieve the Task's outputs​

Before you start

Authenticating with the Signaloid Cloud Compute Engine API

API key authentication

Select a Core

Create a `SourceCode` task request

Submit the Build request

Fetch the Build's status

Retrieve the Builds's outputs

Make a Task execution request

Submit the Task request

Fetch the Task's status

Retrieve the Task's outputs