ATLAS Freedom API

This library is a Rust library which focuses on wrapping the ATLAS Freedom REST API in an easy to use and idiomatic way. The API is entirely asynchronous, support for a blocking client may be added sometime in the future, but for now an executor is required for usage, we recommend tokio.

Installation

To incorporate the Freedom API into an existing cargo project simply invoke the following from the project's root directory:

$ cargo add --git https://github.com/ATLAS-Space-Operations/rust-freedom-api

Getting Started

Once added, simply import the crate's prelude, build a client and make a query:

use freedom_api::prelude::*;
use futures::stream::StreamExt;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build the client, grabbing the API keys from environment variables
    let config = Config::builder()
        .environment(Test)
        .key_from_env()?    // Sources the key from ATLAS_KEY
        .secret_from_env()? // Sources the secret from ATLAS_SECRET
        .build()?;

    let client = Client::from_config(config);

    // Query Freedom for a list of all Satellites, printing the names of the 
    // satellite which passed deserialization
    client.get_satellites()
        .collect::<Vec<_>>()
        .await
        .iter()
        .flatten()
        .for_each(|sat| println!("Satellite Name: {: <20}", sat.name));

    Ok(())
}

Creating Resources

In addition to fetching resources, the API can also be used to create resources for example a task request can be constructed with the following:

use std::time::Duration;

use freedom_api::prelude::*;
use time::OffsetDateTime;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::from_env()?;

    let response = client.new_task_request()
        .test_task("my_test_file.bin")
        .target_time_utc(OffsetDateTime::now_utc() + Duration::from_secs(15 * 60))
        .task_duration(120)
        .satellite_id(1)
        .site_id(2)
        .site_configuration_id(3)
        .band_ids([4, 5, 6])
        .send()
        .await?;

    Ok(())
}

Documentation

The freedom API has a significant amount of documentation to get users up and running quickly. To build the docs, simply run the following from the root of this repository, once cloned.

$ cargo doc --no-deps --open

Chaining API Returns

Many of the data types exposed in this library can be navigated to through other resources, for instance a task request object holds links to the site object the task was scheduled at.

Rather than making a call to fetch the request, then parse the site ID, then request the site from the ID, you can instead fetch the site directly from the return of the request call:

use freedom_api::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = Config::from_env()?;
    let client = Client::from_config(config);

    let site_from_request: Site = client
        .get_request_by_id(42)
        .await?
        .get_site(&client)
        .await?;

    Ok(())
}

API Return Type

Container

You will note that what is returned by the get_ methods of the API is of type Self::Container<T> rather than simply type T. This complexity is required since there are multiple API clients, most notably the default Client and the CachingClient (available via the caching feature flag). The caching client is backed by a concurrent caching system, and in order to avoid unnecessarily cloning all responses from the caching client to the call site, the cached values are stored as Arc<T> so they can be cheaply cloned from the cache. This complexity will be mostly transparent to the caller, since the container is required to implement Deref<T>.

If however you need to mutate the data after receiving it, call the Container::into_inner method on the returned type to get an owned version of the wrapped type.

let mut request = atlas_client
    .get_request_by_id(42)
    .await?
    .into_inner();