diff --git a/docs/docs/api/routes/games.md b/docs/docs/api/routes/games.md new file mode 100644 index 000000000..fa34287ed --- /dev/null +++ b/docs/docs/api/routes/games.md @@ -0,0 +1,78 @@ +# Game Endpoints + +These endpoints cover all games and specific games. For +specific playtypes, see [Game:Playtype Endpoints](./gpt.md). + +***** + +## Retrieve all supported games. + +`GET /api/v1/games` + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `supportedGames` | String[] | The list of games this service supports. | +| `configs` | Record<Game, [GameConfig](../../codebase/implementation-details/game-configuration.md)> | Contains a mapping of every supported game to its configuration. | + +### Example + +#### Request +``` +GET /api/v1/games +``` + +#### Response + +```json +{ + "supportedGames": ["iidx", "bms"], + "configs": { + "iidx": { + "name": "beatmania IIDX", + // ... + }, + "bms": { + "name": "BMS", + // ... + } + } +} +``` + +***** + +## Retrieve a specific games' configuration. + +`GET /api/v1/games/:game` + +### Parameters + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `` | GameConfig | The configuration for this game. | + +### Example + +#### Request +``` +GET /api/v1/games/iidx +``` + +#### Response + +```json +{ + "defaultPlaytype": "SP", + "name": "beatmania IIDX", + "internalName": "iidx", + "validPlaytypes": ["SP", "DP"], +} +``` diff --git a/docs/docs/api/routes/gpt.md b/docs/docs/api/routes/gpt.md new file mode 100644 index 000000000..0dccd793d --- /dev/null +++ b/docs/docs/api/routes/gpt.md @@ -0,0 +1,31 @@ +# Game:Playtype Endpoints + +These endpoints are for games + their playtypes. +To find out what games are supported by a service +programmatically, you should see [Game Endpoints](./games.md). + +***** + +## Retrieve Game:Playtype Configuration. + +`GET /api/v1/games/:game/:playtype` + +### Parameters + +### Response + +| Property | Type | Description | +| :: | :: | :: | + + +### Example + +#### Request +``` + +``` + + + +#### Response + diff --git a/docs/docs/api/routes/user-gamept.md b/docs/docs/api/routes/user-gamept.md index bec0edc30..f97e6c581 100644 --- a/docs/docs/api/routes/user-gamept.md +++ b/docs/docs/api/routes/user-gamept.md @@ -12,9 +12,9 @@ This endpoints are for specific users information on specific game + playtype co | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | + + + ### Response @@ -68,9 +68,9 @@ GET /api/v1/users/zkldi/games/iidx/SP | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | + + + | `unachieved` (Optional) | Presence | If present, only unachieved goals are returned. | ### Response @@ -122,9 +122,9 @@ GET /api/v1/users/zkldi/games/iidx/SP/goals | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | + + + | `unachieved` (Optional) | Presence | If present, only unachieved milestones are returned. | ### Response @@ -172,9 +172,9 @@ GET /api/v1/users/zkldi/games/iidx/SP/milestones | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | + + + | `search` | String | Limits the returned scores to those where the corresponding song is most similar to this query. | ### Response @@ -236,9 +236,9 @@ different rating algorithm to sort under. | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | + + + | `alg` | String | An overriding rating algorithm to use instead of the default. | ### Response @@ -309,10 +309,10 @@ GET /api/v1/users/zkldi/games/iidx/SP/pbs/best?alg=BPI | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | -| `:chartID` | URL Parameter | The chart to retrieve this user's PB for. | + + + + | `getComposition` | Presence | If present, the individual ScoreDocuments that composed this PB will also be returned. | ### Response @@ -356,9 +356,9 @@ GET /api/v1/users/1/games/iidx/SP/pbs/some_chart_id | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | + + + | `search` | String | Limits the returned scores to those where the corresponding song is most similar to this query. | ### Response @@ -421,9 +421,9 @@ GET /api/v1/users/zkldi/games/iidx/SP/scores?search=Verfl | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | + + + ### Response @@ -482,9 +482,9 @@ song titles of played songs inside sessions. | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | + + + | `search` | string | The session name to search for. | ### Response @@ -528,9 +528,9 @@ These are returned in descending order. | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | + + + | `alg` (Optional) | string | The name of the algorithm to use instead of the default. | ### Response @@ -587,9 +587,9 @@ These are returned in descending order according to `timeEnded`. | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The ID or username of the user to retrieve information from. | -| `:game` | URL Parameter | The game to retrieve information from. Must be a supported game. | -| `:playtype` | URL Parameter | The playtype to retrieve information for. Must be a supported playtype of the previous game. | + + + ### Response diff --git a/docs/docs/api/routes/users.md b/docs/docs/api/routes/users.md index b67a142ac..8dbbeabb1 100644 --- a/docs/docs/api/routes/users.md +++ b/docs/docs/api/routes/users.md @@ -49,7 +49,7 @@ GET /api/v1/users | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The user's userID or their username. | + !!! note The :userID param has some special functionality, @@ -105,7 +105,7 @@ GET /api/v1/users/me WHEN authenticated as userID 1. | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The user ID or username to fetch the data of. | + ### Response diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index b15b34609..cd6bf2b6b 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -50,7 +50,10 @@ nav: - "api/routes/users.md" - "api/routes/user-gamept.md" - "api/routes/sessions.md" + - "api/routes/scores.md" - "api/routes/search.md" + - "api/routes/games.md" + - "api/routes/gpt.md" - Codebase Reference: - "codebase/overview.md"