polaris-api

Async Rust API client for the Black Duck Polaris platform.

polaris-api provides a high-level, async client for common Polaris workflows: authentication, project and branch discovery, issue queries, triage updates, and analysis metrics.

Features

• Async-first client built on tokio + reqwest
• API token authentication with automatic JWT retrieval and caching
• Pagination helpers (list_all_*) for project/branch/issue traversal
• Triage workflows (get_triage, update_triage, get_triage_history)
• Issue analytics (roll-up counts, trends over time, issue age, discovery endpoints)
• Typed models for common JSON:API entities and response metadata
• Consistent error handling via PolarisError

Installation

cargo add polaris-api

Quick start

use polaris_api::client::{PolarisClient, PolarisConfig};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = PolarisConfig {
        base_url: std::env::var("POLARIS_BASE_URL")?,
        api_token: std::env::var("POLARIS_API_TOKEN")?,
    };
    let client = PolarisClient::new(config);

    let projects = client.list_all_projects(None, 50).await?;
    for project in projects.data {
        println!("{} ({})", project.attributes.name, project.id);
    }

    Ok(())
}

Environment variables:

• POLARIS_BASE_URL (example: https://your-instance.polaris.blackduck.com)
• POLARIS_API_TOKEN (API token from Polaris user settings)

API surface (high level)

Authentication

• authenticate

Projects and branches

• list_projects, list_all_projects
• list_branches, list_all_branches

Issues and details

• list_issues, list_all_issues
• get_issue
• get_events_with_source
• get_source_code

Triage

• get_triage
• update_triage
• get_triage_history

Metrics and discovery

• get_roll_up_counts
• get_issues_over_time
• get_issue_age
• get_filter_keys
• get_group_bys

Errors

Most operations return Result<T, PolarisError>, where PolarisError includes:

• HTTP transport errors
• auth failures
• API status/detail errors
• deserialization errors
• typed NotFound cases

Security notes

• The client uses bearer-token auth over HTTPS and sets explicit API headers.
• JWTs are cached in memory and wrapped with zeroize::Zeroizing.
• The crate denies unsafe operations in unsafe functions (#![deny(unsafe_op_in_unsafe_fn)]).

Relationship to this repository

This crate lives in the polaris-cli workspace and is used by the companion CLI binary crate (polaris-cli/) for terminal workflows.

License

MIT