Riven

Rust Library for the Riot Games API.

Riven's goals are speed, reliability, and maintainability. Riven handles rate limits and large requests with ease. Data structs and endpoints are automatically generated from the Riot API Reference (Swagger).

Design

• Fast, asynchronous, thread-safe.
• Automatically retries failed requests, configurable.
• Supports all endpoints, kept up-to-date using riotapi-schema.
• Can compile to Wasm for server-side or browser+proxy use.

Usage

use riven::RiotApi;
use riven::consts::PlatformRoute;

// Enter tokio async runtime.
let rt = tokio::runtime::Runtime::new().unwrap();
rt.block_on(async {
    // Create RiotApi instance from key string.
    let api_key = std::env!("RGAPI_KEY"); // "RGAPI-01234567-89ab-cdef-0123-456789abcdef";
    let riot_api = RiotApi::new(api_key);

    // The region.
    let platform = PlatformRoute::NA1;

    // Get account data.
    let account = riot_api.account_v1()
        .get_by_riot_id(platform.to_regional(), "잘 못", "NA1").await
        .expect("Get summoner failed.")
        .expect("There is no summoner with that name.");

    // Print account name#tag.
    println!(
        "{}#{} Champion Masteries:",
        account.game_name.unwrap_or_default(),
        account.tag_line.unwrap_or_default(),
    );

    // Get champion mastery data.
    let masteries = riot_api.champion_mastery_v4()
        .get_all_champion_masteries_by_puuid(platform, &account.puuid).await
        .expect("Get champion masteries failed.");

    // Print champion masteries.
    for (i, mastery) in masteries.iter().take(10).enumerate() {
        println!("{: >2}) {: <9}    {: >7} ({})", i + 1,
            mastery.champion_id.name().unwrap_or("UNKNOWN"),
            mastery.champion_points, mastery.champion_level);
    }
});

Output:

잘 못 Champion Masteries:
 1) Riven        1236866 (7)
 2) Fiora         230679 (5)
 3) Katarina      175985 (5)
 4) Lee Sin       156070 (7)
 5) Jax           102662 (5)
 6) Gnar           76373 (6)
 7) Kai'Sa         64271 (5)
 8) Caitlyn        46614 (5)
 9) Irelia         46465 (5)
10) Vladimir       37176 (5)

The RiotApi struct documentation contains additional usage information. The tests and example proxy provide more example usage.

Feature Flags

Nightly vs Stable

Enable the nightly feature to use nightly-only functionality. This enables nightly optimizations in the parking_lot crate.

riven = { version = "...", features = [ "nightly" ] }

rustls

Riven uses reqwest for making requests. By default, reqwest uses the native TLS library. If you prefer using rustls you can do so by turning off the Riven default features and specifying the rustls-tls feature:

riven = { version = "...", default-features = false, features = [ "rustls-tls" ] }

tracing (or log)

By default Riven logs some diagnostic information using log. If the tracing feature is enabled, Riven will use tracing which usefully aguments logs with per-request span information.

metrics

The metrics feature enables some rudiementary metrics collecting via the metrics crate. See #76 for details. More metrics may be added in the future.

Docs

On docs.rs.

Error Handling

Riven returns either Result<T> or Result<Option<T>> within futures.

If the Result is errored, this indicates that the API request failed to complete successfully, which may be due to bad user input, Riot server errors, incorrect API key, etc.

If the Option is None, this indicates that the request completed successfully but no data was returned. This happens in several situations, such as getting an account (by name#tag) or match (by id) that doesn't exist, or getting spectator data for a summoner who is not in-game. Specifically, the API returned an HTTP 404 (or 204) status code.

The error type returned by Riven is RiotApiError. It provides some basic diagnostic information, such as the source reqwest error, the number of retries attempted, and the reqwest Response object.

By default, Riven retries up to 3 times (4 requests total). Some errors, such as 400 client errors, are not retried as they would inevitably fail again.

You can configure Riven by creating a RiotApiConfig instance, setting the desired config values, and passing that to RiotApi::new (instead of just the API key). For example, you can configure the number of times Riven retries using RiotApiConfig::set_retries(...).

Semantic Versioning

This package follows semantic versioning to an extent. However, the Riot API itself changes often and does not follow semantic versioning, which makes things difficult. Keep Riven up-to-date as out-of-date versions will slowly cease to work.

When the API changes, this may result in breaking changes in the models module, endpoints module, and some of the consts module. Models may receive new fields (and, less frequently, have fields removed), endpoints may be added or removed, and new enum variants may be added. These breaking changes will increment the MINOR version, not the major version. (major.minor.patch)

Parts of Riven that do not depend on Riot API changes do follow semantic versioning.

Auto-Updating

Riven may be configured to automatically update its generated code from the latest version of the riotapi-schema. This requires an internet connection, violates semantic versioning, and may break your build. To enable auto-updating, set the riven_autogen cfg option for rustc (not a cargo feature).

If the build configuration doesn't change, then the generated code will be cached and not subsequently update. To change the build configuration and force an update you can set the RIVEN_AUTOGEN_NONCE environment variable to a new value.

For example, setting RIVEN_AUTOGEN_NONCE to the current date will trigger an update once a day, assuming the build configuration otherwise doesn't change:

RUSTFLAGS="--cfg riven_autogen" RIVEN_AUTOGEN_NONCE="$(date +%Y-%m-%d)" cargo build

Additional Help

Feel free to make an issue if you are have any questions or trouble with Riven.

Development

Riven is a regular cargo package for the most part, and can be built directly from the repository source code without additional consideration. However source files with names matching *.gen.rs have been automatically generated by the riven/build build script. The build script is set up to be skipped by default; to actually update the generated files run ./srcgen.bash.

Build Script Configuration

The the riven_autogen cfg option (for rustc, not a cargo feature) enables the build script. If unset, the build script is not even compiled, which ensures fast builds when Riven is used as a dependency. If set, the build script will be compiled but the actual behavior depends on the RIVEN_AUTOGEN_DEVMODE environment variable. If unset or set to "outdir", will behave as in the auto-update section above, generating files to OUT_DIR to be used by Riven instead of the checked-in src files. If set to "src", the build script will overwrite the files in src directly (this is what ./autogen_src.bash does). If set to "none", the build script will be built but will not generate any files. This is the default for the repository, set in .cargo/config.toml, to avoids extraneous updates.

The build script will not generally re-run after the initial build, unless the RIVEN_AUTOGEN_NONCE environment variable changes, or something else in the build configuration changes.

Testing

To run tests put your API key into either the RGAPI_KEY environment variable or the apikey.txt file.