Foru.ms Rust Library

The Foru.ms Rust library provides convenient access to the Foru.ms APIs from Rust.

Table of Contents

• Documentation
• Installation
• Reference
• Usage
• Errors
• Request Types
• Advanced
  • Retries
  • Timeouts
  • Additional Headers
  • Additional Query String Parameters

Documentation

API reference documentation is available here.

Installation

Add this to your Cargo.toml:

[dependencies]
foru_ms_sdk = "0.0.40"

Or install via cargo:

cargo add foru_ms_sdk

Reference

A full reference for this library is available here.

Usage

Instantiate and use the client with the following:

use foru_ms_sdk::prelude::*;

#[tokio::main]
async fn main() {
    let config = ClientConfig {
        api_key: Some("<value>".to_string()),
        ..Default::default()
    };
    let client = ForumClient::new(config).expect("Failed to build client");
    client
        .auth
        .register(
            &PostAuthRegisterRequest {
                username: "username".to_string(),
                email: "email".to_string(),
                password: "password".to_string(),
                display_name: None,
                roles: None,
                bio: None,
                extended_data: None,
            },
            None,
        )
        .await;
}

Errors

When the API returns a non-success status code (4xx or 5xx response), an error will be returned.

match client.auth.register(None)?.await {
    Ok(response) => {
        println!("Success: {:?}", response);
    },
    Err(ApiError::HTTP { status, message }) => {
        println!("API Error {}: {:?}", status, message);
    },
    Err(e) => {
        println!("Other error: {:?}", e);
    }
}

Request Types

The SDK exports all request types as Rust structs. Simply import them from the crate to access them:

use foru_ms_sdk::prelude::{*};

let request = PostAuthRegisterRequest {
    ...
};

Advanced

Retries

The SDK is instrumented with automatic retries with exponential backoff. A request will be retried as long as the request is deemed retryable and the number of retry attempts has not grown larger than the configured retry limit (default: 2).

A request is deemed retryable when any of the following HTTP status codes is returned:

• 408 (Timeout)
• 429 (Too Many Requests)
• 5XX (Internal Server Errors)

Use the max_retries method to configure this behavior.

let response = client.auth.register(
    Some(RequestOptions::new().max_retries(3))
)?.await;

Timeouts

The SDK defaults to a 30 second timeout. Use the timeout method to configure this behavior.

let response = client.auth.register(
    Some(RequestOptions::new().timeout_seconds(30))
)?.await;

Additional Headers

You can add custom headers to requests using RequestOptions.

let response = client.auth.register(
    Some(
        RequestOptions::new()
            .additional_header("X-Custom-Header", "custom-value")
            .additional_header("X-Another-Header", "another-value")
    )
)?
.await;

Additional Query String Parameters

You can add custom query parameters to requests using RequestOptions.

let response = client.auth.register(
    Some(
        RequestOptions::new()
            .additional_query_param("filter", "active")
            .additional_query_param("sort", "desc")
    )
)?
.await;