A nodejs library for calling algorithms on Algorithmia.com with partial support for the DataAPI
The official Algorithmia nodejs client is available on NPM.
Install it for your project by adding algorithmia
to your package.json:
npm install --save algorithmia
Set runtime environment variables by creating .env
file in the root directory with the following keys
Name | Value | Purpose |
---|---|---|
ALGORITHMIA_API_ADDRESS | <key for Algorithmia api url> |
Optional, will default to https://api.algorithmia.com |
ALGORITHMIA_DEFAULT_API_KEY | <secret key to run Algorithmia api> |
Required for algorithmia client |
Then instantiate an Algorithmia client using your API key environment variables:
const algorithmia = require('algorithmia');
let client: AlgorithmiaClient = algorithmia.getClient(process.env.ALGORITHMIA_DEFAULT_API_KEY);
Now you are ready to call algorithms.
The following examples of calling algorithms are organized by type of input/output which vary between algorithms.
Note: a single algorithm may have different input and output types, or accept multiple types of input, so consult the algorithm's description for usage examples specific to that algorithm.
Call an algorithm with text input by passing a string into the pipe
method.
The returned promise will be called with the response with the Algorithm completes (or when an error occurs).
If the algorithm output is text, then the get()
method on the response will return a string.
const response = await client.algo("algo://demo/Hello/0.1.1").pipe("HAL 9000");
// -> Hello HAL 9000
Call an algorithm with JSON input by passing in a native JavaScript type;
most of the time this will be an Object
or an Array
(though Boolean
, Number
, and Null
are possible).
const response = await client.algo("algo://WebPredict/ListAnagrams/0.1.0").pipe(["transformer", "terraforms", "retransform"]);
// -> ["transformer","retransform"]
Call an algorithm with binary input by passing a Buffer
into the pipe method.
var buffer = fs.readFileSync("/path/to/bender.jpg");
const response = await client.algo("opencv/SmartThumbnail").pipe(buffer);
// -> Buffer(...)
If an error occurs when calling an algorithm, the response will contain an error field that you can check:
const response = await client.algo('util/whoopsWrongAlgo').pipe('Hello, world!');
The Algorithmia API exposes parameters to configure algorithm requests including support for changing the timeout of indicating that the API should include stdout in the response. Currently, the node.js client exposes these as query paremeters to the algorithm URI:
client.algo("algo://demo/Hello/0.1.1?timeout=10&stdout=true").pipe("HAL 9000");
Note: stdout=true
is only supported if you have access to the algorithm source.
The Algorithmia client also provides a way to manage both Algorithmia hosted data and data from Dropbox or S3 accounts that you've connected to you Algorithmia account.
Create directories by instantiating a DataDir
object and calling create()
:
let dir: DataDir = Algorithmia.getClient(process.env.ALGORITHMIA_DEFAULT_API_KEY).dir('Insert directory path');
await dir.create('Insert directory path');
Upload files by calling the file
method a DataDir
object or put
on a DataFile
object:
let file: DataFile = Algorithmia.getClient(process.env.ALGORITHMIA_DEFAULT_API_KEY).file('Insert file path');
await file.put('Insert your file body');
let dir: DataDir = Algorithmia.getClient(process.env.ALGORITHMIA_DEFAULT_API_KEY).dir('Insert directory path');
let file: DataFile = dir.file('Insert file path');
await dir.put(file.baseName(), 'Insert your file body');
let dir = Algorithmia.getClient(process.env.ALGORITHMIA_DEFAULT_API_KEY).dir('Insert directory path');
await dir.putFile(resolve('Insert local file path'));
Download files by calling get
on a DataFile
object:
let file: DataFile = Algorithmia.getClient(process.env.ALGORITHMIA_DEFAULT_API_KEY).file('Insert file path');
const response = await file.get();
let dir: DataDir = Algorithmia.getClient(process.env.ALGORITHMIA_DEFAULT_API_KEY).dir('Insert directory path');
const response = await dir.get();
Delete files by calling delete
on their respective DataFile
or DataDir
object.
When deleting directories, you may optionally specify a force
argument
that indicates whether or not a directory should be deleted if it contains files or other directories (default = false
).
let file: DataFile = Algorithmia.getClient(process.env.ALGORITHMIA_DEFAULT_API_KEY).file('Insert file path');
const response = await file.delete();
let dir: DataDir = Algorithmia.getClient(process.env.ALGORITHMIA_DEFAULT_API_KEY).dir('Insert directory path');
const response = await dir.delete(true);
Name | Parameters | Example |
---|---|---|
Get Algorithm | String userName - Your Algorithmia user name. String algoName - The name address of the algorithm. |
const algorithm: Algorithm = JSON.parse(await Algorithmia.getClient(key).getAlgo(userName, algoName)); |
List Algorithm Versions | String userName - Your Algorithmia user name. String algoName - The name address of the algorithm. Boolean callable - Whether to return only public or private algorithm versions. Integer limit - Items per page. Boolean published - Whether to return only versions that have been published. String marker - Marker for pagination. |
const algorithmVersionsList: AlgorithmVersionsList = JSON.parse(await Algorithmia.getClient(key).listAlgoVersions(userName, algoName)); |
List Algorithm Builds | String userName - Your Algorithmia user name. String algoName - The name address of the algorithm. Integer limit - Items per page. String marker - Marker for pagination. |
const algorithmBuildsList: AlgorithmBuildsList = JSON.parse(await Algorithmia.getClient(key).listAlgoBuilds(userName, algoName)); |
Get Algorithm Build Logs | String userName - Your Algorithmia user name. String algoName - The name address of the algorithm. String buildId - The id of the build to retrieve logs. |
const response: [] = JSON.parse(await Algorithmia.getClient(key).getAlgoBuildLogs(userName, algoName, buildId)); |
Delete Algorithm | String userName - Your Algorithmia user name. String algoName - The name address of the algorithm. |
const response = await Algorithmia.getClient(key).deleteAlgo(userName, algoName); |
Create Algorithm | String userName - Your Algorithmia user name. String requestString - JSON payload for the Algorithm you wish to create. |
const algorithm: Algorithm = JSON.parse(await Algorithmia.getClient(key).createAlgo(userName, algoJson)); |
List Cluster SCM’s | - | const response: SCM[] = JSON.parse(await Algorithmia.getClient(key).listSCMs()); |
Get SCM | String scmId - The id of scm to retrive | const scm: SCM = JSON.parse(await Algorithmia.getClient(key).getSCM(scmId)); |
Query SCM Authorization Status | String scmId - The id of scm status to retrive | const scmAuth: AlgorithmSCMAuthorizationStatus = JSON.parse(await Algorithmia.getClient(key).querySCMStatus(scmId)); |
This project uses typescript compile.
npm install typescript -g && npm install @types/node
tsc
Note: Don't edit the .js in the lib
directory; they will get overwritten on subsequent compiles.
Instead, modify .ts
files in the src
dir, and run tsc
.