Crate brawl_api

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).

Re-exports

pub use constants::Brawlers;

pub use http::client::Client;

pub use time::TimeLike;

pub use model::common::StarPower;

pub use model::players::Player;

pub use model::players::PlayerClub;

pub use model::players::PlayerBrawlerStat;

pub use model::players::battlelog::BattleLog;

pub use model::players::battlelog::Battle;

pub use model::players::battlelog::BattleEvent;

pub use model::players::battlelog::BattleResultInfo;

pub use model::players::battlelog::BattlePlayer;

pub use model::players::battlelog::BattleBrawler;

pub use model::players::battlelog::BattleOutcome;

pub use model::clubs::Club;

pub use model::clubs::ClubMember;

pub use model::clubs::ClubMembers;

pub use model::clubs::ClubMemberRole;

pub use model::clubs::ClubType;

pub use model::rankings::players::PlayerLeaderboard;

pub use model::rankings::players::PlayerRanking;

pub use model::rankings::players::PlayerRankingClub;

pub use model::rankings::clubs::ClubLeaderboard;

pub use model::rankings::clubs::ClubRanking;

pub use model::rankings::brawlers::BrawlerLeaderboard;

pub use model::brawlers::BrawlerList;

pub use model::brawlers::Brawler;

pub use error::Error;

pub use error::Result;

Modules

constants	Contains constant values used within the lib.
error	Contains the Error enum, used in all functions of the library that may error (fetches).
http	Module related to the internals of fetching and requesting to the Brawl Stars API.
model	Contains models for each documented Brawl Stars API endpoint.
prelude	Useful re-exports for usage with this library. It is recommended to use brawl_api::prelude::*.
time	Contains the TimeLike struct, used to indicate strings that contain timestamps which can be parsed using TimeLike.parse (if the chrono feature is enabled, otherwise the method is not implemented).
traits	Traits used by the library. Those are of mostly internal use and normally shouldn't need implementation by some user-made type.

Macros

b_api_concat	Concats string(s) to the main API URI.
map_build	Constructs any Map<Key, Value> type, based on an initializer expression.