gca3020 / GABoardGameGeek

BoardGameGeek XMLAPI2 Swift Framework for interacting with games and collections on BGG
MIT License
8 stars 6 forks source link

GABoardGameGeek

gitlab-workflow Version Swift version swift-package-manager Platform License Twitter

BoardGameGeek XMLAPI2 Swift Framework for interacting with games and collections on BGG

Features

Requirements

Dependencies

Communication

Example & Unit Tests

To run the unit tests, and see some additional usage details, clone the repo, and run pod install from the Example directory first.

Installation

GABoardGameGeek is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "GABoardGameGeek"

Usage

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.

Searching for a Game

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.

Reading a Game by ID

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

Getting a User's Collection

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

Handling Results

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.

Error Handling

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:


Changelog

See CHANGELOG for a list of all changes and their corresponding versions.

License

GABoardGameGeek is released under the MIT license. See LICENSE for details.