rbgg/
lib.rs

1/*!
2# rbgg
3This is a library that allows you to conveniently use the boardgamegeek.com
4APIs. This is a pretty thin wrapper over the APIs, so with the documentation
5on BGG's site and the docs here, you should be able to get up and running
6quickly.
7
8API version 1: https://boardgamegeek.com/wiki/page/BGG_XML_API
9API version 2: https://boardgamegeek.com/wiki/page/BGG_XML_API2
10
11The basics of this library are pretty simple. You make a call that matches up
12with the API, like [search](https://t.brk.io/2I) after creating a client and
13you get a
14[serde_json::Value](https://docs.rs/serde_json/latest/serde_json/#operating-on-untyped-json-values)
15response that contains the converted XML.
16
17## Blocking and Async are supported
18The other items to be aware of in this library is that `async` calls are the
19default, but blocking calls are supported by simply appending "_b" to the end
20of the method name.
21
22For example, if you want to call the `search()` method, here are the ways
23in which you would do this.
24
25```rust
26use rbgg::bgg2::*;
27
28// There's also a Client2::new() that allows you to change root url and
29// API path, but unless you have some specfic use case, you want to use
30// the defaults.
31let client = Client2::new_from_defaults();
32// Calling the search function async. I'll note that all results, both async
33// and sync, will be `Result<Value>`
34let result = client.search("bruges", &vec![Search::BoardGame], None).await?;
35
36// Similarly, calling it using a blocking call
37let result = client.search_b("bruges", &vec![Search::BoardGame], None)?;
38```
39
40## API v2
41While API v1 tracks pretty much exactly the [documentation on BGG's
42site](https://boardgamegeek.com/wiki/page/BGG_XML_API) and, technically, so
43does [API v2](https://boardgamegeek.com/wiki/page/BGG_XML_API), but with
44some additional convenience methods.
45
46For example, the [thing](https://t.brk.io/WW) API allows you to specify IDs
47and one or more things to get.  While you're welcome to use that raw API, each
48of the "things" has it's own direct call.  Here are a couple of examples,
49first using the direct thing API, then the `boardgame()` convenience method.
50
51```rust
52use rbgg::{bgg2::*, utils::Params};
53
54let client = Client2::new_from_defaults();
55// You can set any of the parameters for the call using the `Params` in the
56// utils lib.
57let params = Params::from([
58  ("comments".into(), "1".into()),
59  ("stats".into(), "1".into()),
60]);
61// You can retrieve more than 1 item at a time
62let game_ids = vec![136888, 133473];
63let ttypes = vec![Thing::BoardGame];
64
65// We'll use the blocking call in this example
66let res = client.thing_b(&game_ids, &ttypes, Some(params));
67
68// Alternatively, you can implicitly just use the "thing" type of boardgame.
69// Here is the same call with the convenience function.
70let res = client.boardgame_b(&game_ids, Some(params));
71```
72
73There are similar methods for all of the [family items](https://t.brk.io/j4) as
74well.
75
76Beyond that, you are pretty much just following what the docs say on BGG's
77site as that's what the library implements.  Happy gaming!
78
79## Caveats to Be Aware Of
80* The library doesn't do things like automatic pagination
81  collection.  So, if there is more than 1 page of results, it is up to you
82  to handle this.  The upside is that you have easy access to this data.
83* If there is an error in the response itself, it is up to you to handle that
84  in the JSON response. It will look something like this:
85
86```json
87{
88  "error": {
89    "message": "Rate limit exceeded."
90  }
91}
92```
93 */
94extern crate reqwest;
95extern crate serde_json;
96extern crate urlencoding;
97extern crate xmltojson;
98
99pub mod bgg1;
100pub mod bgg2;
101pub mod utils;
rbgg/lib.rs

rbgg/
lib.rs
