94 stable releases
2.57.0 | Nov 4, 2024 |
---|---|
2.56.0 | Jul 20, 2024 |
2.53.0 | Jun 12, 2024 |
2.38.2 | Mar 27, 2024 |
0.1.2 | Nov 14, 2019 |
#852 in Games
115 downloads per month
545KB
8K
SLoC
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" ] }
log
or tracing
Riven is additionally able to produce tracing spans for requests if the tracing
feature is enabled.
By default the tracing
feature is disabled and Riven instead writes to log
.
Docs
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.
Additional Help
Feel free to make an issue if you are have any questions or trouble with Riven.
Development
NodeJS is used to generate code for Riven. The
riven/srcgen
folder contains the code and doT.js
templates. index.js
lists the JSON files downloaded and used to generate the
code.
To set up the srcgen, you will first need to install NodeJS. Then enter the
riven/srcgen
folder and run npm ci
(or npm install
) to install
dependencies.
To run the srcgen use node riven/srcgen
from the repository root.
Dependencies
~5–20MB
~297K SLoC