brawl-api 0.1.2

A Rust implementation of the Brawl Stars API (https://developer.brawlstars.com/).
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143

//! The `brawl-api` crate creates models and fetching methods employing the
//! [official Brawl Stars API](https://developer.brawlstars.com). 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:
//!
//! ```rust
//! 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:
//!
//! ```rust
//! 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).
//!
//! [`reqwest` crate]: https://crates.io/crate/reqwest
//! [`serde`]: https://crates.io/crate/serde
//! [`serde-json`]: https://crates.io/crate/serde-json
//! [`Serialize`]: https://docs.rs/serde/*/ser/trait.Serialize.html
//! [`Deserialize`]: https://docs.rs/serde/*/de/trait.Deserialize.html
//! [`Player::fetch`]: model/players/player/struct.Player.html#method.fetch
//! [`TimeLike.parse`]: time/struct.TimeLike.html#method.parse
//! [`chrono::DateTime<chrono::Utc>`]: https://docs.rs/chrono/*/chrono/struct.DateTime.html
//! [`model`]: model/index.html
//! [`prelude`]: prelude/index.html
//! [`Brawlers`]: constants/enum.Brawlers.html
//! [`model::players`]: model/players/index.html
//! [`model::clubs`]: model/clubs/index.html
//! [`model::rankings`]: model/rankings/index.html
//! [`model::brawlers`]: model/brawlers/index.html

pub(crate) mod util;

pub(crate) mod serde;

pub mod constants;
pub use constants::Brawlers;

pub mod http;
pub use http::client::Client;

mod macros;

pub mod model;

pub mod time;
pub use time::TimeLike;

#[cfg(any(feature = "players", feature = "brawlers"))]
pub use model::common::StarPower;

#[cfg(feature = "players")]
pub use model::players::{
    Player, PlayerClub, PlayerBrawlerStat,
    battlelog::{
        BattleLog,
        Battle, BattleEvent, BattleResultInfo,
        BattlePlayer, BattleBrawler, BattleOutcome,
    },
};

pub mod traits;

#[cfg(feature = "clubs")]
pub use model::clubs::{Club, ClubMember, ClubMembers, ClubMemberRole, ClubType};

#[cfg(feature = "rankings")]
pub use model::rankings::{
    players::{PlayerLeaderboard, PlayerRanking, PlayerRankingClub},
    clubs::{ClubLeaderboard, ClubRanking},
    brawlers::BrawlerLeaderboard,
};

#[cfg(feature = "brawlers")]
pub use model::brawlers::{BrawlerList, Brawler};

pub mod error;
pub use error::{Error, Result};

pub mod prelude;

//#[cfg(test)]
//mod tests {
//    #[test]
//    fn it_works() {
//        assert_eq!(2 + 2, 4);
//    }
//}