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 -Pnative
to 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
- 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
- shaikezr's solution to caching Mono<?> : https://github.com/shaikezr/async-cacheable (until spring-projects/spring-framework#17920 gets released)