Spring Boot application acting as a proxy to BoardGameGeek's XML API, XML API 2, as well as their undocumented 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.

• 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

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

Steps :

1. clone this repository on your local machine
2. run mvn spring-boot:run
3. navigate to http://localhost:8080/bgg-api/swagger-ui.html or http://localhost:8080/bgg-api/graphiql

Prerequisites : have GraalVM 22+ (java17) 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 5 minutes)
3. run ./target/bgg-api
4. navigate to http://localhost:8080/bgg-api/swagger-ui.html or http://localhost:8080/bgg-api/graphiql

Prerequisites : have docker installed on your machine

Steps :

1. run docker pull ghcr.io/tnaskali/bgg-api:master (or any other tag)
2. run docker run --rm -p 8080:80 tnaskali/bgg-api:master
3. navigate to http://localhost:8080/bgg-api/swagger-ui.html or http://localhost:8080/bgg-api/graphiql

Prerequisites : have docker installed on your machine

Steps :

1. run docker pull ghcr.io/tnaskali/bgg-api-native:master (or any other tag)
2. run docker run --rm -p 8080:8080 tnaskali/bgg-api-native:master
3. navigate to http://localhost:8080/bgg-api/swagger-ui.html or http://localhost:8080/bgg-api/graphiql

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

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

The games logging API will prompt for your BGG username and password. These 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. Then the API will use a secure HTTPS connection to perform authentication to boardgamegeek.com.

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.

• 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

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