ALFA API

An explanation on how to use the ALFA API

Widget Brain Algorithm API (User)

Introduction

This documentation will cover the usage of the ALFA API. It will explain how to authorize, use and get the status of algorithm runs.

The only language binding currently available is in JavaScript, but don't let that stop you. You can view code examples in the dark area to the right.

Authentication

HTTP Request

POST https://baas.widgetbrain.io/requestToken

var request = require("request");

var options = { method: 'POST',
  url: 'https://baas.widgetbrain.io/requestToken',
  headers:
  {
  },
  form:
  {
    clientId: '$clientId',
    clientSecret: '$clientSecret'
   }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  // body will contain the response
});

Make sure to replace $clientId and $clientSecret with the information you can find within the ALFA portal.

Parameter Description
clientId The Client ID provided to you. The client ID should have 32 characters.
clientSecret The Client Secret provided. The Client Secret should have 64 characters.

Response

The response will provide the Bearer token which is valid for 1 hour and can be used to submit algorithm requests

{
    "response":
    {
        "access_token":"$bearerToken",
        "expires_in":86400,
        "token_type":"Bearer"
    }
}

Algorithm

submitRequest

var request = require("request");

var options = { method: 'POST',
  url: 'https://baas.widgetbrain.io/api/Algorithms/submitRequest',
  headers:
    {
        'wb-authorization': 'Bearer $bearerToken',
    },
    form:
    {
        "problem": $jsonProblem,
        "algorithmId": $algorithmId,
        "environment": $environment,
        "returnHoldingResponse": true,
        "callbackEndpoint": {"url": "https://returnurl", "token": $returntoken},
        "includeDetails": false
    }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns JSON which will be structured based on the algorithm called

This endpoint allows you to submit a request to the Algorithm.

HTTP Request

POST https://baas.widgetbrain.io/api/algorithms/submitRequest

Query Parameters

Parameter Type Description
algorithmId string The algorithm ID you would like to run.
enviroment string The algorithm environment you would like to run.
problem string The (stringified) json problem definition. Each algorithm will have a different problem definition and response, see your authorised problem definitions below.
returnHoldingResponse boolean Whether to immediately return a holding response with an algorithm run ID or whether to wait until a response is received
callbackEndpoint object Provide an endpoint which can accept the JSON with the result of the algorithm run, will only work when returnHoldingResponse is set to true
includeDetails boolean Whether to include the details of the run or not (the original problem, the start time, end time, etc.)

Headers

Header Type Description
wb-authorization string The structure of the header should be 'Bearer $bearerToken' where bearerToken is the token from the requestToken call

getStatus

const request = require("request");

const options = { method: 'GET',
  url: `https://baas.widgetbrain.io/api/AlgorithmRuns/getStatus/${$algorithmRunId}`,
  headers:
    {
        'wb-authorization': 'Bearer $bearerToken',
    },
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The above command returns the status of an algorithm run and its result if it is finished.

HTTP Request

GET https://baas.widgetbrain.io/api/AlgorithmRuns/getStatus/$algorithmRunId

Query Parameters

Parameter Type Description
algorithmRunId string The ID of the algorithm run for which to return the status

Headers

Header Type Description
wb-authorization string The structure of the header should be 'Bearer $bearerToken' where bearerToken is the token from the requestToken call

Response

Status code Body Description
200 Result of the algorithm run The algorithm run has finished and the response thus contains the result of the algorithm. If includeDetails of the request was set to true, the response will also contains additional details such as the problem, start time, end time, etc.
204 empty The algorithm run has not finished yet