From a7120cfe2818c9202afde7e7a2c222d20dbf68ef Mon Sep 17 00:00:00 2001 From: mja00 Date: Sun, 21 Dec 2025 16:33:54 -0500 Subject: [PATCH 1/2] fix: actually pull latest stable build --- src/content/docs/misc/downloads-service.mdx | 46 +++++++++++++++++---- 1 file changed, 37 insertions(+), 9 deletions(-) diff --git a/src/content/docs/misc/downloads-service.mdx b/src/content/docs/misc/downloads-service.mdx index 93fdb73f6..1c8b09011 100644 --- a/src/content/docs/misc/downloads-service.mdx +++ b/src/content/docs/misc/downloads-service.mdx @@ -78,26 +78,54 @@ PROJECT="paper" MINECRAFT_VERSION="\{LATEST_PAPER_RELEASE}" USER_AGENT="cool-project/1.0.0 (contact@me.com)" -# First check if the version exists -VERSION_CHECK=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds) +# First check if the requested version has a stable build +BUILDS_RESPONSE=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds) # Check if the API returned an error -if echo "$VERSION_CHECK" | jq -e '.ok == false' > /dev/null 2>&1; then - ERROR_MSG=$(echo "$VERSION_CHECK" | jq -r '.message // "Unknown error"') +if echo "$BUILDS_RESPONSE" | jq -e '.ok == false' > /dev/null 2>&1; then + ERROR_MSG=$(echo "$BUILDS_RESPONSE" | jq -r '.message // "Unknown error"') echo "Error: $ERROR_MSG" exit 1 fi -# Get the download URL directly, or null if no stable build exists -PAPERMC_URL=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT}/versions/${MINECRAFT_VERSION}/builds | \ - jq -r 'first(.[] | select(.channel == "STABLE") | .downloads."server:default".url) // "null"') +# Try to get a stable build URL for the requested version +PAPERMC_URL=$(echo "$BUILDS_RESPONSE" | jq -r 'first(.[] | select(.channel == "STABLE") | .downloads."server:default".url) // "null"') +FOUND_VERSION="$MINECRAFT_VERSION" + +# If no stable build for requested version, find the latest version with a stable build +if [ "$PAPERMC_URL" == "null" ]; then + echo "No stable build for version $MINECRAFT_VERSION, searching for latest version with stable build..." + + # Get all versions for the project (using the same endpoint structure as the "Getting the latest version" example) + # The versions are organized by version group, so we need to extract all versions from all groups + # Then sort them properly as semantic versions (newest first) + VERSIONS=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT} | \ + jq -r '.versions | to_entries[] | .value[]' | \ + sort -V -r) + + # Iterate through versions to find one with a stable build + for VERSION in $VERSIONS; do + VERSION_BUILDS=$(curl -s -H "User-Agent: $USER_AGENT" https://fill.papermc.io/v3/projects/${PROJECT}/versions/${VERSION}/builds) + + # Check if this version has a stable build + STABLE_URL=$(echo "$VERSION_BUILDS" | jq -r 'first(.[] | select(.channel == "STABLE") | .downloads."server:default".url) // "null"') + + if [ "$STABLE_URL" != "null" ]; then + PAPERMC_URL="$STABLE_URL" + FOUND_VERSION="$VERSION" + echo "Found stable build for version $VERSION" + break + fi + done +fi if [ "$PAPERMC_URL" != "null" ]; then # Download the latest Paper version curl -o server.jar $PAPERMC_URL - echo "Download completed" + echo "Download completed (version: $FOUND_VERSION)" else - echo "No stable build for version $MINECRAFT_VERSION found :(" + echo "No stable builds available for any version :(" + exit 1 fi ``` From 411b4ef682f4418715514b9ff6d3b0be7b7ade37 Mon Sep 17 00:00:00 2001 From: mja00 Date: Sun, 21 Dec 2025 16:39:09 -0500 Subject: [PATCH 2/2] chore: update GraphQL examples for pagination --- src/content/docs/misc/downloads-service.mdx | 131 +++++++++++++++----- 1 file changed, 97 insertions(+), 34 deletions(-) diff --git a/src/content/docs/misc/downloads-service.mdx b/src/content/docs/misc/downloads-service.mdx index 1c8b09011..de3fefcd5 100644 --- a/src/content/docs/misc/downloads-service.mdx +++ b/src/content/docs/misc/downloads-service.mdx @@ -136,6 +136,7 @@ do not receive support. ## GraphQL API examples Fill also supports a GraphQL API, which can be accessed at `https://fill.papermc.io/graphql`. +Fill's GraphQL API uses standard pagination, which you can learn more about [here](https://graphql.org/learn/pagination/). A built-in GraphQL playground is available at https://fill.papermc.io/graphiql?path=/graphql. Common API tools such as Postman will introspect the API and provide a UI for building queries. @@ -143,9 +144,14 @@ Common API tools such as Postman will introspect the API and provide a UI for bu ### Getting the latest version ```graphql query LatestVersion { - project(id: "paper") { - versions(last: 1) { - id + project(key: "paper") { + key + versions(first: 1, orderBy: {direction: DESC}) { + edges { + node { + key + } + } } } } @@ -158,11 +164,16 @@ query LatestVersion { { "data": { "project": { - "versions": [ - { - "id": "1.21.6" - } - ] + "key": "paper", + "versions": { + "edges": [ + { + "node": { + "key": "1.21.11" + } + } + ] + } } } } @@ -173,10 +184,20 @@ query LatestVersion { ### Getting the latest stable build number ```graphql query LatestStableBuild { - project(id: "paper") { - versions(last: 1) { - builds(filterBy: { channel: STABLE }, last: 1) { - id + project(key: "paper") { + key + versions(first: 1, orderBy: {direction: DESC}) { + edges { + node { + key + builds(filterBy: { channel: STABLE }, first: 1, orderBy: { direction: DESC }) { + edges { + node { + number + } + } + } + } } } } @@ -190,15 +211,25 @@ query LatestStableBuild { { "data": { "project": { - "versions": [ - { - "builds": [ - { - "id": 46 + "key": "paper", + "versions": { + "edges": [ + { + "node": { + "key": "1.21.10", + "builds": { + "edges": [ + { + "node": { + "number": 48 + } + } + ] + } } - ] - } - ] + } + ] + } } } } @@ -209,11 +240,27 @@ query LatestStableBuild { ### Getting the latest stable build download URL ```graphql query LatestStableBuildDownloadURL { - project(id: "paper") { - versions(last: 1) { - builds(filterBy: { channel: STABLE }, last: 1) { - download(name: "server:default") { - url + project(key: "paper") { + key + versions(first: 1, orderBy: {direction: DESC}) { + edges { + node { + key + builds(filterBy: { channel: STABLE }, first: 1, orderBy: { direction: DESC }) { + edges { + node { + number + download(key: "server:default") { + name + url + checksums { + sha256 + } + size + } + } + } + } } } } @@ -228,17 +275,33 @@ query LatestStableBuildDownloadURL { { "data": { "project": { - "versions": [ - { - "builds": [ - { - "download": { - "url": "https://fill-data.papermc.io/v1/objects/bfca155b4a6b45644bfc1766f4e02a83c736e45fcc060e8788c71d6e7b3d56f6/paper-1.21.6-46.jar" + "key": "paper", + "versions": { + "edges": [ + { + "node": { + "key": "1.21.10", + "builds": { + "edges": [ + { + "node": { + "number": 48, + "download": { + "name": "paper-1.21.10-48.jar", + "url": "https://fill-data.papermc.io/v1/objects/bfca155b4a6b45644bfc1766f4e02a83c736e45fcc060e8788c71d6e7b3d56f6/paper-1.21.10-48.jar", + "checksums": { + "sha256": "bfca155b4a6b45644bfc1766f4e02a83c736e45fcc060e8788c71d6e7b3d56f6" + }, + "size": 54185955 + } + } + } + ] } } - ] - } - ] + } + ] + } } } }