Algorithmia Rust Client Library
A rust client library for the Algorithmia API.
Getting started
The Algorithmia Rust client is published to crates.io.
Add algorithmia = "2.0.0"
to the dependencies in your Cargo.toml
and run cargo install
.
Instantiate an Algorithmia client using your API key:
use Algorithmia;
let client = client;
Now you're ready to call algorithms.
Calling algorithms
This client provides an Algorithm
type (generally created by client.algo(..)
) which provides
methods for calling an algorithm hosted on the Algorithmia platform.
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.
Text input/output
Call an algorithm with text input by simply passing &str
into Algorithm::pipe
.
If the algorithm output is text, call the as_string
method on the response.
let algo = client.algo;
let response = algo.pipe.unwrap;
println!;
JSON input/output
Call an algorithm with JSON input calling pipe
with a reference to a type that implements serde::Serialize
.
If the algorithm output is JSON, you can call decode
to deserialize the resonse into a type that implements serde::Deserialize
.
This includes many primitive types, tuples, Vec
, and other collection types from the standard library:
let algo = client.algo;
let response = algo.pipe.unwrap;
let output: = response.decode.unwrap;
// -> ["transformer", "retransform"] as Vec<String>
Implementing Serialize
or Deserialize
for your custom types is generally as easy as adding a derive
annotation.
// now you can call `pipe` with `&MyStruct` or `decode` into `MyStruct`
With serde_json
, you can also sue the json!
macro or implement custom serialization/deserialization.
See serde.rs for more details on using serde.
Alternatively, you can work with raw JSON strings:
let response = algo.pipe_json;
let output = response.as_json.unwrap.to_string;
// -> "[\"transformer\", \"retransform\"]"
Binary input/output
Call an algorithm with binary input by calling the pipe
method with a slice of bytes (&[u8]
).
If the algorithm response is binary data, then call the as_bytes
method on the response
to obtain a byte vector (Vec<u8>
).
let mut input = Vec new;
open.read_to_end;
let response = client.algo.pipe.unwrap;
let output = response.as_bytes.unwrap;
// -> Vec<u8>
Error handling
True to the nature of explicit error handling in rust,
the pipe
and response parsing methods all return Result
-wrapped types:
let algo = client.algo;
match algo.pipe
// -> error calling demo/Hello: apply() functions do not match input data
Note: this crate makes use of the error-chain
crate, so for many error variants,
there may be additional errors chained to err.cause()
.
Request options
The client exposes options that can configure algorithm requests via a builder pattern. This includes support for changing the timeout or indicating that the API should include stdout in the response.
let mut algo = client.algo;
let algo = algo.timeout.stdout;
let response = algo.pipe.unwrap;
if let Some = response.metadata.stdout
Note: stdout(true)
is ignored if you do not have access to the algorithm source.
Managing data
The Algorithmia Rust 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.
This client provides a DataFile
type (generally created by client.file(uri)
)
and a DataDir
type (generally created by client.dir(uri)
) that provide methods for managing your data.
Create directories
Create directories by instantiating a DataDir
object and calling create()
with a DataAcl
:
let robots = client.dir;
robots.create
let robots = client.dir;
robots.create
Upload files to a directory
Upload files by calling put
on a DataFile
object, or by calling put_file
on a DataDir
object.
let robots = client.dir;
// Upload local file
robots.put_file;
// Write a text file
robots..put;
// Write a binary file
robots..put;
Download contents of file
Download files by calling get
on a DataFile
object
which returns a Result
-wrapped DataResponse
that implements Read
:
// Download and locally save file
let mut t800_png_reader = client.file.get.unwrap;
let mut t800_png = create.unwrap;
copy;
// Get the file's contents as a string
let mut t800_text_reader = robots.file.get.unwrap;
let mut t800_text = String new;
t800_text_reader.read_to_string;
// Get the file's contents as a byte array
let mut t800_png_reader = robots.file.get.unwrap;
let mut t800_bytes = Vec new;
t800_png_reader.read_to_end;
Delete files and directories
Delete files and directories by calling delete on their respective DataFile
or DataDir
object.
DataDirectories take a force
parameter that indicates whether the directory should be deleted if it contains files or other directories.
client.file.delete;
client.dir.delete;
List directory contents
Iterate over the contents of a directory using the iterator returned by calling list
on a DataDir
object:
let my_robots = client.dir;
for entry in my_robots.list
Examples
For examples that use this client, see:
- Basic test examples
- Algorithmia CLI - CLI build with this client
- Algorithmia FUSE - experimental filesystem build with this client
Build & Test
This project is built and tested with cargo:
Pro-tip: before building docs, clone existing docs to track changes