iri-client

Rust client + Python bindings for the NERSC IRI API OpenAPI 3.1 spec in openapi/openapi.json.

Python Bindings

Install from PyPI:

pip install iri-client

or build the extension module locally:

# Use maturin >= 1.9.4
maturin develop --features python

Python operation examples

import json
from iri_client import Client

client = Client(base_url="https://api.iri.nersc.gov")

# List operation ids
operations = Client.operations()
print(f"Loaded {len(operations)} operations from generated catalog")
print("First 10 operations:")
for operation in operations[:10]:
    print(f"  - {operation.operation_id} ({operation.method} {operation.path_template})")

# Public operation
print(client.call_operation("getFacility"))

# Path params
print(
    client.call_operation(
        "getSite",
        path_params_json=json.dumps({"site_id": "dd7f822a-3ad2-54ae-bddb-796ee07bd206"}),
    )
)

# Auth-required operation
# access_token = "<token from GlobusAuth>"
# auth_client = Client(base_url="https://api.iri.nersc.gov", access_token=access_token)
# print(auth_client.call_operation("getProjects"))

Full runnable Python operation script:

• examples/python_module_example.py
• examples/python_async_module_example.py (async with AsyncClient)
• examples/submit_job.py (submit a job to IRI api and monitor status)

Authentication Model

This API uses header Authorization with the raw access token value:

Authorization: <access_token>

This client follows that behavior when you call with_authorization_token(...) or pass access_token=... to the client's constructor in Python.

Runnable Cargo Examples

These are checked-in Rust examples you can run directly:

# Lists generated operation ids/methods/paths (no network calls)
cargo run --example blocking_list_operations

# Calls getResources with query parameters
cargo run --example blocking_get_resources

# Same example with custom base URL and limit
IRI_BASE_URL=https://api.iri.nersc.gov IRI_RESOURCE_LIMIT=10 \
  cargo run --example blocking_get_resources

# Calls auth-required getProjects
IRI_ACCESS_TOKEN=<access-token> cargo run --example blocking_get_projects

# Async IriClient examples
cargo run --example async_get_resources
IRI_ACCESS_TOKEN=<access-token> cargo run --example async_get_projects

# Async ApiClient example (raw path + query)
cargo run --example async_api_client_sites

CLI Tool

A small CLI binary iri-cli is included. One can install it through cargo. It is currently not distributed in the python package.

cargo install iri-client --features cli

Here are a few examples on how to use the cli client.

# Show generated operations
iri-cli operations

# Filter operation ids
iri-cli operations --filter Job

# Call by OpenAPI operation id with query params
iri-cli call getResources --query group=perlmutter --query resource_type=compute

# Call operation with path params
iri-cli call getSite --path-param site_id=<site-id>

# Raw method/path request
iri-cli request GET /api/v1/facility/sites --query limit=5

# Authenticated operation
IRI_ACCESS_TOKEN=<access-token> \
  iri-cli call getProjects

Rust Examples (OpenAPI Operation Client)

Use IriClient when calling by OpenAPI operationId.

Public endpoint: getFacility

use iri_client::IriClient;

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

    let facility = client
        .call_operation("getFacility", &[], &[], None)
        .await?;

    println!("{facility}");
    Ok(())
}

Query parameters: getResources

use iri_client::IriClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = IriClient::new("https://api.iri.nersc.gov")?;

    let resources = client
        .call_operation(
            "getResources",
            &[],
            &[("limit", "10"), ("offset", "0"), ("resource_type", "compute")],
            None,
        )
        .await?;

    println!("{resources}");
    Ok(())
}

Path parameter: getSite

use iri_client::IriClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = IriClient::new("https://api.iri.nersc.gov")?;

    let site = client
        .call_operation("getSite", &[("site_id", "dd7f822a-3ad2-54ae-bddb-796ee07bd206")], &[], None)
        .await?;

    println!("{site}");
    Ok(())
}

Auth-required endpoint: getProjects

use iri_client::IriClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let access_token = std::env::var("IRI_ACCESS_TOKEN")?;
    let client = IriClient::new("https://api.iri.nersc.gov")?
        .with_authorization_token(access_token);

    let projects = client
        .call_operation("getProjects", &[], &[], None)
        .await?;

    println!("{projects}");
    Ok(())
}

Rust Examples (Generic REST Client)

Use ApiClient when you want direct method/path control.

use iri_client::ApiClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = ApiClient::new("https://api.iri.nersc.gov")?;

    let sites = client
        .get_json_with_query("/api/v1/facility/sites", &[("limit", "5"), ("offset", "0")])
        .await?;

    println!("{sites}");
    Ok(())
}