docs: rewrite GetGameRankAndScore page (#8)

RetroAchievements · Dec 29, 2023 · e038f16 · e038f16
1 parent ae68993
commit e038f16
Show file tree

Hide file tree

Showing 5 changed files with 95 additions and 111 deletions.
diff --git a/README.md b/README.md
@@ -46,7 +46,7 @@ Click the function names to open their complete docs on the docs site.
 - [Extended Details](https://api-docs.retroachievements.org/v1/games/detailed-info.html) - Get extended metadata about a game.
 - [Achievement IDs](https://api-docs.retroachievements.org/v1/games/achievement-ids.html) - Get the list of achievement IDs for a game.
 - [Unlocks Distribution](https://api-docs.retroachievements.org/v1/games/achievement-distribution.html) - Get how many players have unlocked how many achievements for a game.
-- [`GetGameRankAndScore`](https://api-docs.retroachievements.org/v1/games/get-game-rank-and-score.html) - Get a list of either the latest masters or highest points earners for a game.
+- [High Scores](https://api-docs.retroachievements.org/v1/games/high-scores.html) - Get a list of either the latest masters or highest hardcore points earners for a game.
 - [`GetGameRating`](https://api-docs.retroachievements.org/v1/games/get-game-rating.html) - Get how users have rated a game.
 
 ### Achievement

diff --git a/docs/.vitepress/config.mts b/docs/.vitepress/config.mts
@@ -118,8 +118,8 @@ export default defineConfig({
             link: "/v1/games/achievement-distribution",
           },
           {
-            text: "Game Rank and Score",
-            link: "/v1/games/get-game-rank-and-score",
+            text: "High Scores",
+            link: "/v1/games/high-scores",
           },
           {
             text: "Game Rating",

diff --git a/docs/public/high-scores.png b/docs/public/high-scores.png
diff --git a/docs/v1/games/get-game-rank-and-score.md b/docs/v1/games/get-game-rank-and-score.md
diff --git a/docs/v1/games/high-scores.md b/docs/v1/games/high-scores.md
@@ -0,0 +1,92 @@
+<script setup>
+import SampleRequest from '../../components/SampleRequest.vue';
+</script>
+
+# High Scores
+
+A call to this function will retrieve metadata about either the latest masters for a game, or the highest points earners for a game. The game is targeted via its unique ID.
+
+[[toc]]
+
+## On-site Representation
+
+When browsing a game page, for example, [Sonic the Hedgehog](https://retroachievements.org/game/1), a table representing the high scores can be seen on the page's sidebar:
+
+![High Scores](/high-scores.png)
+
+## HTTP Request
+
+<SampleRequest httpVerb="GET">https://retroachievements.org/API/API_GetGameRankAndScore.php?g=14402</SampleRequest>
+
+### Query Parameters
+
+| Name | Required? | Description                                                        |
+| :--- | :-------- | :----------------------------------------------------------------- |
+| `z`  | Yes       | Your username.                                                     |
+| `y`  | Yes       | Your web API key.                                                  |
+| `i`  | Yes       | The target game ID.                                                |
+| `t`  |           | 1 for latest masters. 0 for non-master high scores. Defaults to 0. |
+
+## Client Library
+
+::: code-group
+
+```ts [NodeJS]
+import {
+  buildAuthorization,
+  getGameRankAndScore,
+} from "@retroachievements/api";
+
+// First, build your authorization object.
+const userName = "<your username on RA>";
+const webApiKey = "<your web API key>";
+
+const authorization = buildAuthorization({ userName, webApiKey });
+
+// Then, make the API call.
+const gameRankAndScore = await getGameRankAndScore(authorization, {
+  gameId: 14402,
+  type: "latest-masters",
+});
+```
+
+:::
+
+## Response
+
+How entities are ordered in this response should be noted. For `latest-masters`, the first entry will be the most recent mastery for the set. For `high-scores` it will be the first person to master the set.
+
+::: code-group
+
+```json [HTTP Response]
+[
+  {
+    "User": "Arekdias",
+    "NumAchievements": 15,
+    "TotalScore": 219,
+    "LastAward": "2023-06-07 14:43:18"
+  }
+  // ...
+]
+```
+
+```json [NodeJS]
+[
+  {
+    "user": "BruceLee1255",
+    "totalScore": 0,
+    "lastAward": "2019-07-30 23:19:43",
+    "rank": 27
+  }
+  // ...
+]
+```
+
+:::
+
+## Source
+
+| Repo                     | URL                                                                                           |
+| :----------------------- | :-------------------------------------------------------------------------------------------- |
+| RetroAchievements/RAWeb  | https://github.com/RetroAchievements/RAWeb/blob/master/public/API/API_GetGameRankAndScore.php |
+| RetroAchievements/api-js | https://github.com/RetroAchievements/api-js/blob/main/src/game/getGameRankAndScore.ts         |