torn-api.rs

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.