rust-brawl-api

A Rust implementation of the Brawl Stars API (https://developer.brawlstars.com/).

Usage

1. Use cargo (add as dependency on your Cargo.toml).
2. Generate an API key in the Brawl Stars developer website.
3. Code!

For example:

use brawl_api::prelude::*;

fn main() -> Result<(), Box<dyn ::std::error::Error>> {
    let client = Client::new("MYAUTHTOKEN");
    let player = Player::fetch(&client, "#PLAYER_TAG_TO_FETCH")?;
    // now data for player with the given tag is available.
    // See all models in the documentation.
}

License

Licensed under the MIT license (see the LICENSE file).

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be licensed as MIT, without any additional terms or conditions.

lib.rs:

The brawl-api crate creates models and fetching methods employing the official Brawl Stars API. It aims to be an usable, predictable and programmer-friendly library. Anywhere it is not seen as so, contribution is very welcome.

Requesting

All the requesting work is done by the reqwest crate. The library supports both sync (blocking) and, with the async feature (enabled by default), async function styles - all fetching methods with that duality have a sync variant (with its normal name) and an async one (named by prefixing the sync name with a_ - e.g.: fetch (sync) and a_fetch (async)).

Deserialization and data structure

Deserialization of JSON is done thanks to the serde and serde-json libraries, which are of invaluable aid on that aspect. This means that all library models implement the Serialize and Deserialize serde traits, optimized to match the JSON formats documented in the API's official documentation.

In addition, it is noticeable that most API models implement the Default trait. This is for usage with serde, in order to ensure that the values will be there, regardless of an API failure. Fields not marked with Option<T> should be there by most standards - note that the official Brawl Stars API docs state that all fields everywhere are optional (which isn't helpful), even though most of them will always occur unless a server fault or some unexpected, new use-case was added (in which case, the library can be blamed for not being updated - feel free to contribute with a PR, or just an issue poking me about this, adding this to the library!).

For more info on models, see the model module.

Recommended Usage

It is recommended to import the library using its prelude module:

use brawl_api::prelude::*;

This brings into scope all of the library's traits, models and the helper Brawlers enum.

If it is not desired to bring all models into scope, then at least import all traits so that models work properly:

use brawl_api::traits::*;

Feature Flags

The crate has a few feature flags available (all enabled by default):

• async flag:
  • Enables the usage of async (non-blocking) fetch functions - a_fetch, a_fetch_from, a_fetch_into, a_refetch - where applicable.
  • Adds async_trait as a dependency.
• auto-hashtag flag: Enables the smart insertion of hashtags on anywhere a tag is required.
  • This means, for example, that on a Player::fetch call, which requires the tag of the player to be fetched, one can pass a string containing a hashtag at the start (in which case, the library simply uses it) or without (then, with this feature on, the lib adds it automatically).
  • Disabling this requires passing hashtags at the start of every tag string. This is due to how the API parses tags, and not much can be done about it.
• chrono: Adds chrono as dependency and enables the usage of TimeLike.parse, which parses an incoming timestamp into a chrono::DateTime<chrono::Utc>.
• players flag: Enables the usage of the model::players module (for the /players endpoint).
• clubs flag: Enables the usage of the model::clubs module (for the /clubs endpoint).
• rankings flag: Enables the usage of the model::rankings module (for the /rankings endpoint).
• brawlers flag: Enables the usage of the model::brawlers module (for the /brawlers endpoint).