chore: update download service docs (#698)

Author: mja00

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
 ```
 
@@ -108,16 +136,22 @@ 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.
 
 ### 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
+                }
+            }
         }
     }
 }
@@ -130,11 +164,16 @@ query LatestVersion {
 {
     "data": {
         "project": {
-            "versions": [
-                {
-                    "id": "1.21.6"
-                }
-            ]
+            "key": "paper",
+            "versions": {
+                "edges": [
+                    {
+                        "node": {
+                            "key": "1.21.11"
+                        }
+                    }
+                ]
+            }
         }
     }
 }
@@ -145,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
+                            }
+                        }
+                    }
+                }
             }
         }
     }
@@ -162,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
+                                        }
+                                    }
+                                ]
+                            }
                         }
-                    ]
-                }
-            ]
+                    }
+                ]
+            }
         }
     }
 }
@@ -181,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
+                                }
+                            }
+                        }
+                    }
                 }
             }
         }
@@ -200,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
+                                            }
+                                        }
+                                    }
+                                ]
                             }
                         }
-                    ]
-                }
-            ]
+                    }
+                ]
+            }
         }
     }
 }