crates.io Package

Rust SDK (noxaeapi-sdk)

Official async Rust client crate for NoxAeApi REST + WebSocket platform. Built on tokio, reqwest, and serde with complete type safety and automatic retries.

crates.ionoxaeapi-sdkv0.4.1Rust 2021+Tokio AsyncReqwest + Serde

Tokio Async Native

Built for high-performance non-blocking async runtimes powered by Tokio and Reqwest.

13 Core Modules

Complete coverage for players, economy, server, worlds, plugins, LuckPerms, NoxAuth, skills, and Velocity.

Compile-Time Safety

Strict Serde serialization and Rust Result<T, NoxAeApiError> model handling.

Automatic Retries

Built-in exponential backoff with configurable RetryOptions for resilient networking.

Installation

Add noxaeapi-sdk to your Cargo.toml via cargo add or manually in dependencies:

Cargo.toml

# Add to Cargo.toml dependencies:
cargo add noxaeapi-sdk

# With WebSocket streaming support enabled:
cargo add noxaeapi-sdk --features websocket

Basic Usage

Instantiate the NoxAeApiClient with your server base URL and API key:

src/main.rs

use noxaeapi_sdk::NoxAeApiClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = NoxAeApiClient::new("http://localhost:8080", "your-api-key")?;

    // Access any of the 12 core modules async
    let players = client.players().list().await?;
    if let Some(player) = players.first() {
        let balance = client.economy().get_balance(&player.uuid).await?;
        println!("Player balance: $\{:.2\}", balance);
    }

    client.server().broadcast("Hello from the Rust SDK!").await?;
    Ok(())
}

Loading from Environment

Initialize the client automatically from process environment variables without hardcoding secrets:

src/env_example.rs

use noxaeapi_sdk::NoxAeApiClient;

// Reads NOXAEAPI_BASE_URL and NOXAEAPI_KEY from process environment
let client = NoxAeApiClient::from_env()?;

Environment Convention

NoxAeApiClient::from_env() reads NOXAEAPI_BASE_URL and NOXAEAPI_KEY from environment variables.

Realtime WebSocket Streams

Stream live Minecraft server console logs and game events over WebSocket connections:

src/realtime.rs

use noxaeapi_sdk::NoxAeApiClient;

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

    // Connect to live console WebSocket stream
    let mut console_ws = client.connect_console().await?;
    
    while let Some(line) = console_ws.recv().await {
        println!("[Console] {}", line);
    }

    Ok(())
}

WebSocket Feature Flag

WebSocket streaming requires the websocket feature flag in Cargo.toml.

Error Handling & Exceptions

All API methods return Result<T, NoxAeApiError> containing typed error variants:

src/errors.rs

use noxaeapi_sdk::{NoxAeApiClient, NoxAeApiError};

#[tokio::main]
async fn main() {
    let client = NoxAeApiClient::from_env().unwrap();

    match client.server().restart().await {
        Ok(_) => println!("Server restart initiated."),
        Err(NoxAeApiError::Forbidden(msg)) => println!("Permission denied: {}", msg),
        Err(NoxAeApiError::NotFound(msg)) => println!("Resource not found: {}", msg),
        Err(NoxAeApiError::RateLimit) => println!("Rate limit exceeded!"),
        Err(err) => println!("API error: {:?}", err),
    }
}

Error Variant Mapping

NoxAeApiError::Unauthorized401 — API key is missing or rejected

NoxAeApiError::Forbidden403 — API key is valid but lacks permissions for this endpoint

NoxAeApiError::NotFound404 — Target player, world, or resource does not exist

NoxAeApiError::RateLimit429 — Rate limit exceeded (auto-retried when retry is enabled)

NoxAeApiError::ServerError5xx — Minecraft server internal error (auto-retried)

NoxAeApiError::NetworkErrorConnection refused, DNS failure, or socket timeout

Client Configuration

Customize timeouts, retry strategies with exponential backoff, and custom request headers:

src/config.rs

use noxaeapi_sdk::{NoxAeApiClient, RetryOptions};
use std::time::Duration;

let client = NoxAeApiClient::builder()
    .base_url("https://mc.example.com")
    .api_key("your-api-key")
    .timeout(Duration::from_secs(10))
    .retry(RetryOptions {
        attempts: 3,
        base_delay_ms: 300,
        max_delay_ms: 5000,
    })
    .build()?;

Modules Catalog (13)

Browse all 13 sub-modules available under the NoxAeApiClient instance:

Method	Return Type	Description	REST Spec
`list()`	`Result<Vec<OnlinePlayer>, NoxAeApiError>`	Get a vector of all currently online players with locations, health, and metadata.	Endpoint
`list_all()`	`Result<Vec<OfflinePlayer>, NoxAeApiError>`	Get every player the server has ever seen (online + offline).	Endpoint
`get(uuid)`	`Result<PlayerDetail, NoxAeApiError>`	Get in-depth attributes and real-time state for a specific player by UUID.	Endpoint
`get_inventory(player_uuid, world_uuid)`	`Result<Vec<InventorySlot>, NoxAeApiError>`	Inspect a player's armor, hotbar, offhand, and storage inventory slots.	Endpoint
`kick(uuid, reason)`ADMIN	`Result<(), NoxAeApiError>`	Disconnect an online player with an optional kick reason.	Endpoint
`ban(uuid, reason, expiry)`ADMIN	`Result<(), NoxAeApiError>`	Ban a player UUID with optional reason and ISO-8601 expiry timestamp.	Endpoint
`unban(uuid)`ADMIN	`Result<(), NoxAeApiError>`	Remove a player ban entry by UUID.	Endpoint
`teleport(uuid, target)`	`Result<(), NoxAeApiError>`	Teleport player to target coordinates in a specified world dimension.	Endpoint
`set_gamemode(uuid, gamemode)`ADMIN	`Result<(), NoxAeApiError>`	Update active gamemode (Survival, Creative, Adventure, Spectator).	Endpoint
`get_stats(uuid)`	`Result<PlayerStats, NoxAeApiError>`	Fetch gameplay statistics (kills, deaths, playtime, distance walked).	Endpoint
`resolve(player)`	`Result<PlayerProfile, NoxAeApiError>`	Resolve a player UUID or username to a complete PlayerProfile struct.	Endpoint
`get_player_profile(player)`	`Result<PlayerProfile, NoxAeApiError>`	Fetch detailed profile attributes for a player by UUID or username.	Endpoint
`get_player_profiles(players)`	`Result<Vec<PlayerProfile>, NoxAeApiError>`	Batch resolve multiple player UUIDs or usernames in a single async API call.	Endpoint

Usage Example

examples/players_example.rs

use noxaeapi_sdk::{NoxAeApiClient, TeleportTarget, Gamemode};

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

    // List online players async
    let players = client.players().list().await?;
    println!("Online players: {}", players.len());

    // Resolve player profile
    let profile = client.players().resolve("Notch").await?;
    println!("UUID: {}", profile.uuid);

    // Teleport player
    let target = TeleportTarget {
        x: 100.5,
        y: 64.0,
        z: -250.0,
        world: "world".to_string(),
    };
    client.players().teleport(&profile.uuid, &target).await?;

    Ok(())
}

Rust SDK (noxaeapi-sdk)

Tokio Async Native

13 Core Modules

Compile-Time Safety

Automatic Retries

Installation

Basic Usage

Loading from Environment

Realtime WebSocket Streams

Error Handling & Exceptions

Client Configuration

Modules Catalog (13)

Players (client.players())

Economy (client.economy())

Server (client.server())

Worlds (client.worlds())

Plugins (client.plugins())

Advancements (client.advancements())

Placeholders (client.placeholders())

LuckPerms (client.luckperms())

NoxAuth (client.noxauth())

Skills (client.skills())

Leaderboards (client.leaderboards())

Network (client.network())

Network Hub (NoxAeApiNetworkHubClient)

See Also & Integrations

TypeScript / Node.js SDK

Python SDK

Go SDK