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 :
- clone this repository on your local machine
- run
mvn spring-boot:run - 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 :
- clone this repository on your local machine
- run
mvn native:compile -Pnativeto build the native image (takes about 5 minutes) - run
./target/bgg-api - 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 :
- run
docker pull ghcr.io/tnaskali/bgg-api:master(or any other tag) - run
docker run --rm -p 8080:80 tnaskali/bgg-api:master - 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 :
- run
docker pull ghcr.io/tnaskali/bgg-api-native:master(or any other tag) - run
docker run --rm -p 8080:8080 tnaskali/bgg-api-native:master - 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