BoardGameGeek XMLAPI2 Swift Framework for interacting with games and collections on BGG
To run the unit tests, and see some additional usage details, clone the repo, and run pod install
from the Example directory first.
GABoardGameGeek is available through CocoaPods. To install it, simply add the following line to your Podfile:
pod "GABoardGameGeek"
One of the things that I wanted to accomplish with this library is making the common things you would want to do very easy, as well as "Swifty". To that end, here are a number of the things you can do with this library.
One of the very first things you might want to do is to search for a game by name:
import GABoardGameGeek
GABoardGameGeek().searchFor("pandemic") { result in
switch(result) {
case .success(let searchResults):
print(searchResults)
case .failure(let error):
print(error)
}
}
Alternately, you might want to narrow down your search by only searching for exact matches, or only for items of a specific type, like expansions:
import GABoardGameGeek
GABoardGameGeek().searchFor("pandemic: on the brink", searchType: "boardgameexpansion", exactMatch: true) { result in
switch(result) {
case .success(let searchResults):
print(searchResults)
case .failure(let error):
print(error)
}
}
I have some plans for how the search type is specified, as these handful of strings for "type" are used pretty commonly throughout the API, but for now, specifying the string manually gets ths job done.
Once you have a game ID, getting the details for that game is easy:
GABoardGameGeek().getGameById(12345) { result in
switch(result) {
case .success(let game):
print(game)
case .failure(let error):
print(error)
}
}
Of course, you also might want to request a bunch of games at once:
GABoardGameGeek().getGamesById([1, 232, 41415, 12]) { result in
switch(result) {
case .success(let gameList):
print(gameList)
case .failure(let error):
print(error)
}
}
Additionally, you might want game statistics. These can be requested as well for either a single game, or the list of games
GABoardGameGeek().getGameById(12123, stats: true) { result in
switch(result) {
case .success(let game):
print(game)
case .failure(let error):
print(error)
}
}
Likewise, getting a user's collection is also quite easy. Simply specify their username. The result is an ApiResult
containing a CollectionBoardGame
array
GABoardGameGeek().getUserCollection("userName") { result in
switch(result) {
case .success(let gameCollection):
print(gameCollection)
case .failure(let error):
print(error)
}
}
Collection requests have a number of additional, optional parameters. You can request a "brief" collection, which will generally be returned and parsed much quicker, especially for users with large collections, but will not contain as many details about a game as a standard request. You can also request a collection with statistics, which will contain additional information about a game, such as it's overall rating, position in various rankings, and what this particular user has rated it. You can even combine these two parameters, and request brief game details, with a subset of game statistics.
Finally, BoardGameGeek's API generally takes a while to respond to Collection Requests, especially for users
with very large collections. As a result, the call to request a collection has a default timeout of 90
seconds, during which time it will retry, as long as the server continues to respond with a 202
error code.
GABoardGameGeek().getUserCollection("userName", brief: true, stats: true, timeout: 120) { result in
switch(result) {
case .success(let gameCollection):
print(gameCollection)
case .failure(let error):
print(error)
}
}
With heavy inspiration taken from common Swift libraries like Alamofire, the primary way that API results are returned is in an ApiResult container. This container uses Swift Generics to hold values of different types.
If you don't like the Switch syntax, you can also access the results using some computed properties. The following two examples are equivalent:
// Use switch to handle results/errors
GABoardGameGeek().getGameById(12123) { result in
switch(result) {
case .success(let game):
print(game)
case .failure(let error):
print(error)
}
}
// Use accessors to handle results/erros
GABoardGameGeek().getGameById(12123) { result in
if(result.isSuccess) {
print(result.value!)
}
else {
print(result.error!)
}
}
So feel free to choose the syntax you prefer.
Whenever you are dealing with Networking APIs, there are a number of errors that can occur. I've done
my best to prevent the ones I can, but there's nothing I can do when the API goes down, or a network
connection is unavaialable. When that happens, you can either add code to the .failure
case of the
ApiResult
enum, or check result.isFailure
.
There are a few classes of error in the BggError
enumeration:
connectionError
: Something went wrong with the network connection itself, and the API could not be reached.serverNotReady
: Seen when querying a user's collection. The server is not ready yet, but our timeout has expired.apiError
: There was an error in the results of the API, things like invalid usernames will cause this.xmlError
: There was an error parsing the XML response from the API. If you see one of these, please Contact Me
or create an issue with the request you were making and the detail text from the error.See CHANGELOG for a list of all changes and their corresponding versions.
GABoardGameGeek is released under the MIT license. See LICENSE for details.