BGG-API

Spring Boot application acting as a proxy to BoardGameGeek's XML API, XML API 2 and JSON API. Its purpose is to expose the same functionalities, mainly retrieving but also persisting data, in a more user-friendly and developer-friendly way.

Features

• Static BGG XML API schemas in XSD format (located under src/main/xsd)
• Proxied XML and Json API for querying data based on their public API (no authentication required)
• Proxied Json API for mutating data (e.g. logging games) based on their public API (basic authentication required)
• (in progress) custom GraphQL API unifying these different API endpoints (schema under src/main/resources/graphql) and GraphiQL UI (/bgg-api/graphiql) web interface
• OpenAPI definition and Swagger UI (/bgg-api/swagger-ui.html) web interface
• Support for building both Java and native artifacts and images

Setup

build and run a java application locally

Prerequisites : have Java 17+ and maven installed on your machine

Steps :

1. clone this repository on your local machine
2. set your BGG application token through the BGG_APPLICATION_TOKEN environment variable
3. run mvn spring-boot:run

build and run a native application locally

Prerequisites : have GraalVM JDK 17+ and maven installed on your machine

Steps :

1. clone this repository on your local machine
2. run mvn native:compile -Pnative to build the native image (takes about 10 minutes)
3. set your BGG application token through the BGG_APPLICATION_TOKEN environment variable
4. run ./target/bgg-api

pull and run a docker java image (Linux / MacOS only)

Prerequisites : have docker installed on your machine

Steps :

1. run docker pull ghcr.io/tnaskali/bgg-api:master (or any other tag)
2. set your BGG application token through the BGG_APPLICATION_TOKEN environment variable
3. run docker run --rm -p 8080:80 -e BGG_APPLICATION_TOKEN=${BGG_APPLICATION_TOKEN} ghcr.io/tnaskali/bgg-api:master

pull and run a docker native image (Linux / MacOS only)

Prerequisites : have docker installed on your machine

Steps :

1. run docker pull ghcr.io/tnaskali/bgg-api-native:master (or any other tag)
2. set your BGG application token through the BGG_APPLICATION_TOKEN environment variable
3. run docker run --rm -p 8080:80 -e BGG_APPLICATION_TOKEN=${BGG_APPLICATION_TOKEN} ghcr.io/tnaskali/bgg-api-native:master

Usage

Web interfaces

Swagger UI

The Swagger UI is available at http://localhost:8080/bgg-api/swagger-ui.html once the application is running.

GraphiQL UI

The GraphiQL UI is available at http://localhost:8080/bgg-api/graphiql once the application is running.

Authentication

Some JSON API endpoints require authentication. Only basic authentication using your BGG username and password is supported. Under the hood, these will be exchanged for a session cookie used to authenticate requests to BGG.

A word about security

Credentials will be transmitted in clear using unsecured HTTP protocol from your browser to the locally running Spring Boot application and will only be kept in memory for the duration of the session. The API itself will use a secure HTTPS connection to perform authentication to BGG.

Sample request body for logging a play

endpoint: /bgg-api/api/v3/geekplay (POST, basic auth)

{
  "ajax": 1,
  "action": "save",
  "objectid": 1000,
  "objecttype": "thing",
  "playdate": "2023-08-03",
  "comments": "comments go here",
  "length": 60,
  "location": "Home",
  "quantity": 3,
  "players": [
    {
      "name": "Non-BGG Friend",
      "position": "1",
      "color": "blue",
      "score": "18",
      "rating": 7,
      "win": true,
      "new": false
    },
    {
      "username": "tnaskali",
      "new": true
    }
  ]
}

Sample graphQL user query

endpoint: /bgg-api/graphql (POST, no auth)

{
    userByUsername(username: "tnaskali") {
        id,
        firstname,
        lastname,
        username,
        dateregistered,
        supportyears,
        designerid,
        publisherid,
        address {
            city,
            isocountry
        },
        guilds{
            id,
            name,
            manager{
                id,
                username
            },
            members {
                user {
                    id,
                    username
                },
                joined
            }},
        microbadges {
            id,
            name,
            imagesrc
        },
        top{
            boardgame{
                rank,
                id,
                type,
                name
            }
        }
    }
}

Terms of use

This is just a proxy to BoardGameGeek's API, so their terms of use still apply. Be sure to read them before deciding to use this API.

Credits and inspirations

• BGG's XML API 2 : https://boardgamegeek.com/wiki/page/BGG_XML_API2
• BGG's database structure : https://boardgamegeek.com/wiki/page/Database_Structure
• Fisico's thread on BGG forum : https://boardgamegeek.com/thread/1010057/xml-schema-for-bgg-xml-api2
• Reddit Thread on how to log plays programmatically : https://www.reddit.com/r/boardgames/comments/ez86me/uploading_games_plays_to_bgg_programmatically/
• Baeldung's tutorial on Spring Security Custom Authentication Provider : https://www.baeldung.com/spring-security-authentication-provider

Extras

BGG Data model

classDiagram

%% Relationships
    Guild "many" --> "many" User: members
    Guild "many" --> "1" User: manager
    User "1" --* "1" Collection
    Collection "1" --* "many" Collectionitem
    Collectionitem "many" --> "1" Thing
    Collectionitem "many" --> "0..1" Version
    User "many" --* "many" Play
    Play "many" --> "1" Thing
    Play "many" --> "many" User: players
    User "1" --* "many" Geeklist
    Geeklist "1" --* "many" Geeklistitem
    Geeklist "1" --* "many" Tip
    Geeklist "1" --* "many" Reaction
    Geeklistitem "many" --> "1" Thing
    Geeklistitem "1" --* "many" Comment
    Geeklistitem "1" --* "many" Tip
    Geeklistitem "1" --* "many" Reaction
    Blog "1" --* "many" Blogpost
    Blogpost "many" --> "1" User: author
    Blogpost "1" --* "many" Comment
    Blogpost "1" --* "many" Tip
    Blogpost "1" --* "many" Reaction
    Forum "1" --* "many" Thread
    Thread "many" --> "1" User: author
    Thread "many" --> "0..1" Geekitem
    Thread "1" --* "many" Article
    Thread "1" --* "many" Reaction
    User "1" --* "many" Article
    Article "1" --* "many" Tip
    Article "1" --* "many" Reaction
    Geekitem "many" --> "many" Geekitem: linked items
    Geekitem "many" --* "many" Weblink
    Geekitem "many" --> "many" User: fans
    Comment "many" --> "1" User: author
    Comment "1" --* "many" Tip
    Comment "1" --* "many" Reaction
    Reaction "many" --> "1" User: given by
    Tip "many" --> "1" User: given by
%% Inheritance from Object
    Geekitem <|-- Company
    Geekitem <|-- Component
    Geekitem <|-- Event
    Geekitem <|-- Family
    Geekitem <|-- Media
    Geekitem <|-- Person
    Geekitem <|-- Property
    Geekitem <|-- Thing
    Geekitem <|-- Version
    Geekitem <|-- Weblink

Loading