forked from Bram--/bggclient
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request Bram--#27 from Bram--/dev
Improve documentation and file naming.
- Loading branch information
Showing
39 changed files
with
1,031 additions
and
513 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,164 @@ | ||
| # Module BggClient | ||
|
|
||
| BggClient is a API client for the Board Game Geek XML APIs. These APIs work for all geek domains, | ||
| meaning Board games, video games and RPGs can be retrieved. It works on both the JVM and Android ( | ||
| 24+). Before using the BGG APIs please refer to | ||
| the [Terms of Use](https://boardgamegeek.com/wiki/page/XML_API_Terms_of_Use#) for the APIs. Finally | ||
|
|
||
| If you're looking for all Board game IDs and some basic information please refer to | ||
| [this page](https://boardgamegeek.com/data_dumps/bg_ranks) that contains CSV with all boardgames | ||
| instead. | ||
|
|
||
| ## APIs overview | ||
|
|
||
| See [org.audux.bgg.BggClient] for an overview of the APIs | ||
|
|
||
| ## Examples | ||
|
|
||
| Below are few short example more complicated examples can be found in | ||
| the [examples folder](https://github.com/Bram--/bggclient/tree/main/examples). | ||
|
|
||
| ### Simple board game request in Kotlin | ||
|
|
||
| Below is a code snippet that calls the `things` XML2 API retrieving info about "Nucleum" including | ||
| comments left on the game. | ||
|
|
||
| ```kotlin | ||
| runBlocking { | ||
| val response = BggClient.things(ids = arrayOf(396790), comments = true).call() | ||
|
|
||
| print(response.data?.things!![0].name) // Prints "Nucleum" | ||
| } | ||
| ``` | ||
|
|
||
| This returns all information about a `Thing` - in this case a board game including any comments | ||
| users have left on the thing. Comments are paginated and would only return the last 100. | ||
| See [org.audux.bgg.BggClient.things] for the full API. The actual response is `Response<Thing>` | ||
| which is a wrapper that holds the response data or holds an error instead. Depending on what is | ||
| requested (e.g. are comments included in the request?) the object is (partially) | ||
| filled: [org.audux.bgg.response.Thing] | ||
|
|
||
| _Note that `call()` needs to be called in a suspense function._ | ||
|
|
||
| ### Simple board game request in Java | ||
|
|
||
| Using the library in Java is the same as in Kotlin, however it uses a `CompletableFuture` so the | ||
| request and response can be used in Java. | ||
|
|
||
| ```java | ||
| class Example() { | ||
| public static void main(String... arguments) { | ||
| CompletableFuture<Response<Things>> future = | ||
| BggClient.things( | ||
| /* ids= */ new Integer[]{396790}, | ||
| /* types= */ new ThingType[]{}, | ||
| /* stats= */ false, | ||
| /* versions= */ false, | ||
| /* videos= */ false, | ||
| /* marketplace= */ false, | ||
| /* comments= */ true, | ||
| /* ratingComments= */ false) | ||
| .callAsync(); | ||
|
|
||
| // Blocking get - for example purposes only. | ||
| Response<Things> response = future.get(2_000, MILLISECONDS); | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| The same as the Kotlin example above; this returns all information about a `Thing` - in this case a | ||
| board game including any comments | ||
| users have left on the thing. Comments are paginated and would only return the last 100. See | ||
| [org.audux.bgg.BggClient.things] for the full API. The actual response is `Response<Thing>` which is | ||
| a wrapper that holds the response data or holds an error instead. Depending on what is requested ( | ||
| e.g. are comments included in the request?) the object is (partially) | ||
| filled: [org.audux.bgg.response.Thing] | ||
|
|
||
| ### Async request | ||
|
|
||
| Instead of using a suspend function you can also do a request inline by giving a callback. The | ||
| request and response parsing will then be handled using `Dispatchers.IO` and `Dispatchers.DEFAULT`. | ||
| The same as the `things` request above but using callAsync() it looks as follows: | ||
|
|
||
| ```kotlin | ||
| BggClient.things(ids = arrayOf(396790), comments = true).callAsync { response -> | ||
| print(response.data?.things!![0].name) // Prints "Nucleum" | ||
| } | ||
| ``` | ||
|
|
||
| ### Pagination | ||
|
|
||
| Pagination is completely taken care off by the library, a more in-depth example can be found in the | ||
| examples folder. Pagination starts with the initial request i.e. when a `page` parameter is given | ||
| that's the start page and the end page can be configured using the `toPage` param. If no `page` and | ||
| no `toPage` params are given the library will attempt to paginate all pages. | ||
|
|
||
| ```kotlin | ||
| var response = BggClient.things(ids = arrayOf(396790), comments = true).paginate().call() | ||
|
|
||
| // Prints "Loads of comments 524" | ||
| println("Loads of comments! ${response.data?.things!![0].comments?.comments}") | ||
| ``` | ||
|
|
||
| The above codes results in 6 requests to BGG, first, the initial request and then 5 parallel | ||
| requests to retrieve the resulting pages/comments. | ||
|
|
||
| ##### Paginated requests: | ||
|
|
||
| Not all requests can be paginates (as most of them are not actually paginated in the API nor | ||
| need they be). However the following requests can be paginated: | ||
|
|
||
| * `forum` - Aggregate/paginates over the `threads` in a forum. Only 50 per request can be | ||
| retrieved which means that large forums could result in a lot of requests. | ||
| * `guilds` - Aggregate/paginates over the `guildMembers`. Only 25 members can be returned | ||
| per request. | ||
| * `plays` - Aggregates/paginates over the list of `plays` for the given user (id). Only 100 plays | ||
| per request are retrieved. | ||
| * `things` - Aggregates/paginates over the list of `comments` or `ratingcomments`. The pageSize can | ||
| be set but has a default and maximum size of 100 comments per request. | ||
| * `user` - Aggregates/paginates over the list of `buddies` and `guilds`. The default page size is | ||
| 1000 so it's unlikely pagination actually happens when called. | ||
|
|
||
| ### Sitemaps | ||
|
|
||
| Sitemaps are a quick to get IDs of Board games, RPGs, etc. The `sitemapIndex` endpoint contains all | ||
| sitemaps for the given domain e.g. `boardgamegeek.com/sitemapindex` has a list of several sitemaps ( | ||
| UrlSets) that contains links to ALL board game pages. | ||
| You can request the index by calling `BggClient#sitemapIndex`, but using the `diffuse` function will | ||
| actually for off requests to the contained sitemaps and collect the URLs by 'type'. | ||
|
|
||
| ```kotlin | ||
| val response = | ||
| BggClient.sitemapIndex(Domain.BOARD_GAME_GEEK) | ||
| .diffuse(SitemapLocationType.BOARD_GAMES, SitemapLocationType.BOARD_GAME_EXPANSIONS) | ||
| .call() | ||
|
|
||
| println(response.data) | ||
| ``` | ||
|
|
||
| Data contains a (multi) map of types and URLs (`Map<SitemapLocationType, List<SiteMapUrl>>`): | ||
|
|
||
| * [BOARD_GAMES] => ["https://boardgamegeek.com/boardgame/2/dragonmaster", ...] | ||
| * [BOARD_GAME_EXPANSIONS] => ["https://boardgamegeek.com/boardgameexpansion/1573/banzai", ...) | ||
|
|
||
| ### Custom configuration | ||
|
|
||
| `BggClientConfiguration` allows the client to be configured differently. This allows the user to | ||
| increase the maximum number of retries, the maximum number of concurrent requests and how the | ||
| exponential delay is calculated. | ||
|
|
||
| ```kotlin | ||
| BggClient.configure { | ||
| maxConcurrentRequests = 5 | ||
| maxRetries = 100 | ||
| } | ||
| ``` | ||
|
|
||
| ### Logging | ||
|
|
||
| Running into errors/faulty responses? Turn on the internal logging for the library to see the | ||
| internal workings. | ||
|
|
||
| ```kotlin | ||
| BggClient.setLoggerSeverity(Severity.Verbose) | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,19 @@ | ||
| # Package org.audux.bgg | ||
| Core package containing the [BggClient] used for all interactions with this library. | ||
|
|
||
| # Package org.audux.bgg.common | ||
| Enums and classes shared between several requests and responses. | ||
|
|
||
| # Package org.audux.bgg.request | ||
| Contains all code to build requests to BGG. [Request] is the main request object returned when | ||
| calling most APIs, however requests that support pagination might return a specific | ||
| [PaginatedRequest] instead. | ||
|
|
||
| # Package org.audux.bgg.response | ||
| Mostly data classes that wrap the XML response from the BGG APIs. [Response] wraps all data classes | ||
| in order to catch erroneous responses. The [Response] object has [Response.data] which contains the | ||
| parsed (successful) response and [Response.error] is set when the response could not be parsed. The | ||
| latter may happen, for example, when the API returns HTML or an errors like `Guild not found` etc. | ||
|
|
||
| See the [org.audux.bgg.BggClient] for all the requests and associated response data classes. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.