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

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"

TypeScript

  // API token generated from signaloid.io/settings/api
  const apiToken = "scce_yourSignaloidCloudApiKey";

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

  // 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

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

TypeScript

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

Make a Task execution 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 run 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. Running code on the Signaloid Cloud Compute Engine via the Signaloid Cloud Compute Engine API involves four (4) steps:

1. Creating the code execution task request object
2. Submitting the execution task object to obtain a TaskID
3. Using the TaskID to fetch the task status
4. Using the TaskID to fetch the task results if task has completed

Create a SourceCode task request

cURL

The source code execution task object has two parts: (1) the task definition and (2) task overrides. The code snippet below show the TypeScript interfaces the code execution task request object should adhere to.

  type SourceCodeTaskRequest = {
    Type: "SourceCode";
    SourceCode: {
      Object: "SourceCode";
      Code: string;
      Arguments: string;
      Language: "C" | "C++";
    };
    Overrides?: {
      Core?: string;
    };
  };

Note

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

In this example, we will use the task overrides feature to set the ID of the execution core in the task request.

The code below shows the complete task request object:

TASK_OBJECT='{
    "Type": "SourceCode",
    "SourceCode": {
      "Object": "SourceCode",
      "Code": "#include <stdio.h>\n int main() {   printf(\"Hello World\");   return 0; }",
      "Arguments": "",
      "Language": "C"
    },
    "Overrides": {
      "Core": "'$SIGNALOID_CORE_ID'"
    }
  }
'

TypeScript

The source code execution task object has two parts: (1) the task definition and (2) task overrides. The code snippet below show the TypeScript interfaces the code execution task request object should adhere to.

  type SourceCodeTaskRequest = {
    Type: "SourceCode";
    SourceCode: {
      Object: "SourceCode";
      Code: string;
      Arguments: string;
      Language: "C" | "C++";
    };
    Overrides?: {
      Core?: string;
    };
  };

Note

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

In this example, we will use the task overrides feature to set the ID of the execution core in the task request.

The code below shows the complete task request object:

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

  const taskRequest = {
    Type: "SourceCode",
    SourceCode: {
      Object: "SourceCode",
      Code: codeToBeRun,
      Arguments: "",
      Language: "C",
    },
    Overrides: {
      Core: coreID,
    },
  };

Submit the Task request

Once the taskRequest object is initialised, you can make a POST request to /tasks.

cURL

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

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

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

TypeScript

  console.log("Submitting the task to the API...");
  let taskPostResponse;
  try {
    taskPostResponse = await signaloidClient.post("/tasks", taskRequest);
    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": {
    "Object": "Task",
    "TaskID": "tsk_6dcae4d1c4f585901efa12a89a063996",
    "Owner": "yourSignaloidCloudUserID",
    "Application":  {...}, // The application that was submitted to the API
    "Status": "Accepted",
    [...other response keys omitted]
  },
  "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, 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

# 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"

TypeScript

  let taskID = taskPostResponse.data.TaskID;
  let taskStatus = taskPostResponse.data.Status;

  const delay = (ms) => new Promise((res) => setTimeout(res, ms));
  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) {
      // [TODO]: handle errors
    }
  }

  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 /{taskID}/outputs.

cURL

# 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"

TypeScript

  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 outputStream = await axios.get(taskOutputsResponse.data.Stdout);
      console.log(`Task Stdout: ${outputStream.data}`);
    }
  } catch (error) {
    // [TODO]: handle errors
  }

The response will have the following shape:

{
  "data": {
    "Stdout": "...",
    "Stderr": "...",
    "Build": "..."
  },
  "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