Latest 1.0.0
Homepage https://github.com/gca3020/GABoardGameGeek
License MIT
Platforms ios 8.0, osx 10.10, watchos 2.0, tvos 9.0
Dependencies Alamofire, SWXMLHash
Authors

Build Status
codecov.io
Version
Swift version
Platform
License
Twitter

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

Features

  • [x] Read-only access to user collections and games
  • [x] Site Searching
  • [x] TODO! Forums, Videos, Users, Geeklists, etc…
  • [x] Comprehensive Test Coverage & Automated Coverage Reports

Requirements

  • iOS 8.0+, macOS 10.10+, tvOS 9.0+, watchOS 2.0+
  • Xcode 8.1+
  • Swift 3.0

Dependencies

Communication

  • If you’d like to ask a question, use Twitter.
  • If you found a bug, open an issue.
  • If you have a feature request, open an issue.
  • If you want to contribute, submit a pull request.

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:

  • 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.

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.

Latest podspec

{
    "name": "GABoardGameGeek",
    "version": "1.0.0",
    "summary": "A Swift Library for interacting with the BoardGameGeek XMLAPI2",
    "description": "This library provides easy-to-use abstractions for interacting with the BoardGameGeek (BGG) XMLAPI2,nas well as convenient models which provide provide programmatic access to the data, without havingnto deal with the complexities of parsing and error-checking the XML.",
    "homepage": "https://github.com/gca3020/GABoardGameGeek",
    "license": {
        "type": "MIT",
        "file": "LICENSE"
    },
    "authors": {
        "Geoff Amey": "[email protected]"
    },
    "source": {
        "git": "https://github.com/gca3020/GABoardGameGeek.git",
        "tag": "1.0.0"
    },
    "platforms": {
        "ios": "8.0",
        "osx": "10.10",
        "watchos": "2.0",
        "tvos": "9.0"
    },
    "source_files": "GABoardGameGeek/Classes/**/*",
    "dependencies": {
        "Alamofire": [
            "~> 4.0"
        ],
        "SWXMLHash": [
            "~> 3.0"
        ]
    },
    "pushed_with_swift_version": "3.0"
}

Pin It on Pinterest

Share This