Riven/README.md

179 lines
7.5 KiB
Markdown
Raw Normal View History

2021-06-30 23:34:34 +00:00
<h1 align="center">
Riven<br>
</h1>
<p align="center">
<a href="https://github.com/MingweiSamuel/Riven/"><img src="https://cdn.communitydragon.org/latest/champion/Riven/square" width="20" height="20" alt="Riven Github"></a>
<a href="https://crates.io/crates/riven"><img src="https://img.shields.io/crates/v/riven?style=flat-square&logo=rust" alt="Crates.io"></a>
<a href="https://docs.rs/riven/"><img src="https://img.shields.io/badge/docs.rs-Riven-blue?style=flat-square&logo=read-the-docs&logoColor=white" alt="Docs.rs"></a>
2021-09-10 05:40:31 +00:00
<!--<a href="https://travis-ci.com/MingweiSamuel/Riven"><img src="https://img.shields.io/travis/com/mingweisamuel/riven?style=flat-square" alt="Travis CI"></a>-->
2021-06-30 23:34:34 +00:00
<a href="https://github.com/rust-secure-code/safety-dance/"><img src="https://img.shields.io/badge/unsafe-forbidden-green.svg?style=flat-square" alt="unsafe forbidden"></a>
</p>
Rust Library for the [Riot Games API](https://developer.riotgames.com/).
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](https://developer.riotgames.com/api-methods/) ([Swagger](http://www.mingweisamuel.com/riotapi-schema/tool/)).
# Design
2021-06-30 23:34:34 +00:00
* Fast, asynchronous, thread-safe.
2024-03-04 22:40:17 +00:00
* Automatically retries failed requests, configurable.
2021-09-10 05:40:31 +00:00
* Supports all endpoints, kept up-to-date using [riotapi-schema](https://github.com/MingweiSamuel/riotapi-schema).
2024-03-04 22:40:17 +00:00
* Can compile to Wasm for server-side or browser+proxy use.
2021-06-30 23:34:34 +00:00
# Usage
2021-06-30 23:34:34 +00:00
```rust
use riven::RiotApi;
use riven::consts::PlatformRoute;
// Enter tokio async runtime.
2021-09-09 21:54:02 +00:00
let rt = tokio::runtime::Runtime::new().unwrap();
2021-06-30 23:34:34 +00:00
rt.block_on(async {
// Create RiotApi instance from key string.
2021-09-09 21:54:02 +00:00
let api_key = std::env!("RGAPI_KEY"); // "RGAPI-01234567-89ab-cdef-0123-456789abcdef";
let riot_api = RiotApi::new(api_key);
2021-06-30 23:34:34 +00:00
// The region.
let platform = PlatformRoute::NA1;
// Get account data.
let account = riot_api.account_v1()
.get_by_riot_id(platform.to_regional(), "잘 못", "NA1").await
2021-06-30 23:34:34 +00:00
.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(),
);
2021-06-30 23:34:34 +00:00
// Get champion mastery data.
let masteries = riot_api.champion_mastery_v4()
.get_all_champion_masteries_by_puuid(platform, &account.puuid).await
2021-06-30 23:34:34 +00:00
.expect("Get champion masteries failed.");
// Print champion masteries.
2021-06-30 23:34:34 +00:00
for (i, mastery) in masteries.iter().take(10).enumerate() {
println!("{: >2}) {: <9} {: >7} ({})", i + 1,
2021-09-09 21:54:02 +00:00
mastery.champion_id.name().unwrap_or("UNKNOWN"),
2021-06-30 23:34:34 +00:00
mastery.champion_points, mastery.champion_level);
}
});
```
Output:
```text
잘 못 Champion Masteries:
2021-09-09 21:54:02 +00:00
1) Riven 1236866 (7)
2) Fiora 230679 (5)
2021-06-30 23:34:34 +00:00
3) Katarina 175985 (5)
2021-09-09 21:54:02 +00:00
4) Lee Sin 156070 (7)
5) Jax 102662 (5)
2021-06-30 23:34:34 +00:00
6) Gnar 76373 (6)
7) Kai'Sa 64271 (5)
2021-09-09 21:54:02 +00:00
8) Caitlyn 46614 (5)
2021-06-30 23:34:34 +00:00
9) Irelia 46465 (5)
10) Vladimir 37176 (5)
```
The [`RiotApi` struct documentation](https://docs.rs/riven/latest/riven/struct.RiotApi.html)
contains additional usage information. The [tests](https://github.com/MingweiSamuel/Riven/tree/v/2.x.x/riven/tests)
and [example proxy](https://github.com/MingweiSamuel/Riven/tree/v/2.x.x/riven/examples/proxy)
provide more example usage.
2021-06-30 23:34:34 +00:00
## Feature Flags
### Nightly vs Stable
2021-06-30 23:34:34 +00:00
2021-07-04 18:07:56 +00:00
Enable the `nightly` feature to use nightly-only functionality. This enables
2021-06-30 23:34:34 +00:00
[nightly optimizations in the `parking_lot` crate](https://github.com/Amanieu/parking_lot#nightly-vs-stable).
2021-07-04 18:07:56 +00:00
```toml
riven = { version = "...", features = [ "nightly" ] }
```
### rustls
2021-07-04 18:07:56 +00:00
Riven uses [reqwest](https://github.com/seanmonstar/reqwest) for making requests. By default, reqwest uses the native TLS library.
If you prefer using [rustls](https://github.com/ctz/rustls) you can do so by turning off the Riven default features
and specifying the `rustls-tls` feature:
```toml
riven = { version = "...", default-features = false, features = [ "rustls-tls" ] }
```
2024-03-04 22:40:17 +00:00
### `log` or `tracing`
Riven is additionally able to produce [tracing](https://docs.rs/tracing) spans for requests if the `tracing` feature is enabled.
By default the `tracing` feature is disabled and Riven instead writes to [`log`](https://docs.rs/log).
2021-06-30 23:34:34 +00:00
## Docs
2021-06-30 23:34:34 +00:00
[On docs.rs](https://docs.rs/riven/).
## Error Handling
2021-06-30 23:34:34 +00:00
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
2024-04-22 19:55:06 +00:00
as getting an account (by `name#tag`) or match (by id) that doesn't exist, or getting
2021-06-30 23:34:34 +00:00
spectator data for a summoner who is not in-game.
2024-04-22 19:55:06 +00:00
Specifically, the API returned an HTTP 404 (or 204) status code.
2021-06-30 23:34:34 +00:00
2024-04-22 19:55:06 +00:00
The error type returned by Riven is [`RiotApiError`](https://docs.rs/riven/latest/riven/struct.RiotApiError.html).
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`](https://docs.rs/riven/latest/riven/struct.RiotApiConfig.html)
instance, setting the desired config values, and passing that to [`RiotApi::new`](https://docs.rs/riven/latest/riven/struct.RiotApi.html#method.new)
(instead of just the API key). For example, you can configure the number of
times Riven retries using [`RiotApiConfig::set_retries(...)`](https://docs.rs/riven/latest/riven/struct.RiotApiConfig.html#method.set_retries).
2021-06-30 23:34:34 +00:00
## Semantic Versioning
2021-06-30 23:34:34 +00:00
This package follows semantic versioning to an extent. However, the Riot API
itself changes often and does not follow semantic versioning, which makes
2024-04-22 19:55:06 +00:00
things difficult. Keep Riven up-to-date as out-of-date versions will slowly
cease to work.
2021-06-30 23:34:34 +00:00
2024-04-22 19:55:06 +00:00
When the API changes, this may result in breaking changes in the [`models`](https://docs.rs/riven/latest/riven/models/index.html)
module, [`endpoints`](https://docs.rs/riven/latest/riven/endpoints/index.html)
module, and some of the [`consts`](https://docs.rs/riven/latest/riven/consts/index.html)
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`)
2021-06-30 23:34:34 +00:00
Parts of Riven that do not depend on Riot API changes do follow semantic
versioning.
## Additional Help
2021-06-30 23:34:34 +00:00
Feel free to [make an issue](https://github.com/MingweiSamuel/Riven/issues/new)
if you are have any questions or trouble with Riven.
# Development
2021-06-30 23:34:34 +00:00
NodeJS is used to generate code for Riven. The
[`riven/srcgen`](https://github.com/MingweiSamuel/Riven/tree/v/2.x.x/riven/srcgen)
2021-06-30 23:34:34 +00:00
folder contains the code and [doT.js](https://olado.github.io/doT/index.html)
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.
2021-06-30 23:34:34 +00:00
To run the srcgen use `node riven/srcgen` from the repository root.