Crate torn_api

torn-api.rs

Rust Torn API bindings

Async and typesafe bindings for the Torn API that are auto-generated based on the v2 OpenAPI spec.

Installation

torn-api requires an async runtime such as tokio or smol in order to function. It should be fully runtime agnostic when the reqwest feature is disabled.

[dependencies]
torn-api = "1.7"

Features

• reqwest: Include an implementation of the client which uses the reqwest crate as its HTTP client. Requires tokio runtime.
• models: Generate response and parameter model definitions.
• requests: Generate requests model definitions.
• scopes: Generate scope objects which group endpoints by category.
• builder: Generate builders using bon for all request structs.
• strum: Derive EnumIs and EnumTryAs for all auto-generated enums.

Quickstart

use torn_api::{executor::{ReqwestClient, ExecutorExt}, models::RacingRaceTypeEnum};
let client = ReqwestClient::new("XXXXXXXXXXXXX");

let response = client.user().races(|r| r.cat(RacingRaceTypeEnum::Official)).await.unwrap();

let race = &response.races[0];

println!("Race '{}': winner was {}", race.title, race.results[0].driver_id);

Use with undocumented endpoints

The v2 API exposes v1 endpoints as undocumented endpoints in cases where they haven’t been ported over yet. It is still possible (though not recommended) to use this crate with such endpoints by manually implementing the IntoRequest trait.

use torn_api::{
    executor::{ReqwestClient, Executor},
    models::UserId,
    request::{IntoRequest, ApiRequest}
};

#[derive(serde::Deserialize)]
struct UserBasic {
    id: UserId,
    name: String,
    level: i32
}

struct UserBasicRequest(UserId);

impl IntoRequest for UserBasicRequest {
    type Discriminant = UserId;
    type Response = UserBasic;
    fn into_request(self) -> (Self::Discriminant, ApiRequest) {
        let request = ApiRequest {
            path: format!("/user/{}/basic", self.0),
            parameters: Vec::default(),
        };

        (self.0, request)
    }
}

let client = ReqwestClient::new("XXXXXXXXXXXXX");
let basic = client.fetch(UserBasicRequest(UserId(1))).await.unwrap();

Implementing your own API executor

If you don’t wish to use reqwest, or want to use custom logic for which API key to use, you have to implement the Executor trait for your custom executor.

Safety

The crate is compiled with #![forbid(unsafe_code)].

Warnings

• ⚠️ The Torn v2 API, on which this wrapper is based, is under active development and changes frequently. No guarantees are made that this wrapper always matches the latest version of the API.
• ⚠️ This crate contains a lot of macro-heavy, auto-generated code. If you experience slow compile times, you may want try testing the nightly only -Zhint-mostly-unused option to see if improvements in compile time apply to your use case.

Modules

executor

Traits to execute api requests

models

Auto-generated model definitions.

parameters

Auto-generated parameter definitions.

request

Api request traits and auto-generated definitions.

scopes

Auto-generated api categories for convenient access.

Enums

ApiError

Error returned by the API

Error

Error returned by the default Executor

ParameterError

Error for invalid parameter values