Rust

A type-safe, ergonomic Rust client for the Topstats.gg API with async and blocking support.

Crates.io

View the crate page for TopStats' Rust SDK

docs.rs Documentation

Read the full API documentation on docs.rs

Add the dependency to your Cargo.toml:

[dependencies]
topstats = "0.1"
tokio = { version = "1", features = ["full"] }

Initialize the Client

use topstats::Client;

let client = Client::new("YOUR_TOKEN")?;

Make Your First Request

// Get information about a bot
let bot = client.get_bot("583807014896140293").await?;
println!("{} has {:?} servers", bot.name, bot.server_count);

Usage Examples

use topstats::Client;

let client = Client::new("YOUR_TOKEN")?;

// Get detailed bot information
let bot = client.get_bot("583807014896140293").await?;
println!("{} has {:?} servers", bot.name, bot.server_count);

API Reference

Methods

async fn get_bot(&self, bot_id: &str) -> Result<Bot>

// Example
let bot = client.get_bot("583807014896140293").await?;

Response Types

pub struct Bot {
    pub id: String,
    pub name: String,
    pub server_count: Option<i64>,
    pub monthly_votes: i64,
    pub total_votes: i64,
    pub short_description: String,
    pub tags: Vec<String>,
    pub owners: Vec<String>,
    pub deleted: bool,
    pub timestamp: DateTime<Utc>,
    pub percentage_changes: Option<PercentageChanges>,
    // ... and more
}

Feature Flags

The SDK uses Cargo feature flags to control async/blocking mode and the HTTP backend.

Feature	Default	Description
`async`	Yes	Enable async mode
`blocking`	No	Enable blocking (synchronous) mode
`reqwest-client`	Yes	Use `reqwest` as the HTTP backend
`ureq-client`	No	Use `ureq` as the HTTP backend (for blocking mode)
`rustls-tls`	Yes	Use `rustls` for TLS
`native-tls`	No	Use the platform's native TLS
`tracing`	No	Enable `tracing` crate integration

The async and blocking features are mutually exclusive. Enabling both will result in a compile error.

Error Handling

use topstats::Error;

match client.get_bot("invalid-id").await {
    Ok(bot) => println!("Found: {}", bot.name),
    Err(Error::NotFound { message }) => {
        println!("Bot not found: {message}");
    }
    Err(Error::RateLimited { retry_after, .. }) => {
        println!("Rate limited, retry after {retry_after}s");
    }
    Err(e) => eprintln!("Error: {e}"),
}

The API implements rate limiting to ensure fair usage. The Rust SDK handles rate limits automatically by retrying requests when a 429 response is received. You can configure retry behavior using the ClientBuilder:

let client = Client::builder()
    .token("YOUR_TOKEN")
    .auto_retry(true)          // enabled by default
    .max_retries(3)            // default: 3
    .max_delay_threshold(10.0) // max seconds to wait before retrying
    .build()?;

For detailed information about rate limits, see the rate limit documentation.

top-stats/rust-sdk