From 73201fb5d9e83d801194f7cc041d3647ffdfc740 Mon Sep 17 00:00:00 2001 From: zkldi <20380519+zkldi@users.noreply.github.com> Date: Sat, 9 Apr 2022 01:24:29 +0100 Subject: [PATCH] Add all the goal endpoints to gpt-targets --- docs/docs/api/routes/gpt-targets.md | 253 ++++++++++++++++++++++ docs/docs/api/routes/gpt.md | 2 +- docs/docs/tachi-server/documents/chart.md | 2 +- docs/docs/tachi-server/documents/goal.md | 4 +- docs/mkdocs.yml | 3 + 5 files changed, 260 insertions(+), 4 deletions(-) create mode 100644 docs/docs/api/routes/gpt-targets.md diff --git a/docs/docs/api/routes/gpt-targets.md b/docs/docs/api/routes/gpt-targets.md new file mode 100644 index 000000000..18975178b --- /dev/null +++ b/docs/docs/api/routes/gpt-targets.md @@ -0,0 +1,253 @@ +# GPT-Target Endpoints + +These endpoints deal with [targets](../../api/terminology.md) for a Game + Playtype. These are things like searching goals or milestones, or retrieving information about a specific ID. + +For user-specific target endpoints, such as subscriptions, see [UGPT-Target Endpoints](./ugpt-targets.md). + +***** + +## Retrieve this game's recently achieved targets + +`GET /api/v1/games/:game/:playtype/targets/recently-achieved` + +!!! info + This endpoint returns the 100 most recently achieved goal subscriptions, and 50 most recently achieved milestone subscriptions. + + A target is not considered recently achieved if it was [instantly achieved](../../tachi-server/implementation-details/goals-milestones.md#instant-indirect-achievements). + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `goals` | Array<GoalDocument> | The goal documents that were recently achieved. | +| `milestones` | Array<MilestoneDocument> | The milestone documents that were recently achieved. | +| `goalSubs` | Array<GoalSubDocument> | User subscriptions to goals that were recently achieved. | +| `milestoneSubs` | Array<MilestoneSubDocument> | User subscriptions to milestones that were recently achieved. | + +### Example + +#### Request +``` +GET /api/v1/games/iidx/SP/targets/recently-achieved +``` + +#### Response + +```js +{ + goals: [{ + name: "HARD CLEAR 5.1.1 Another", + goalID: "foo" + // ... other goal props + }], + milestones: [{ + name: "Go Beyond Diamond 1", + milestoneID: "bar", + // ... other milestone props + }], + goalSubs: [{ + userID: 1, + goalID: "foo", + achieved: true, + // ... other goalsub props + }], + milestoneSubs: [{ + userID: 3, + milestoneID: "bar", + achieved: true, + // ... other milestone sub props + }] +} +``` + +***** + +## Retrieve this game's recently interacted-with targets + +`GET /api/v1/games/:game/:playtype/targets/recently-interacted` + +!!! info + This endpoint returns the 100 most recently interacted-with goal subscriptions, and 50 most recently interacted-with milestone subscriptions. + + A recently interacted with target subscription is one where `progress` or `outOf` has changed recently. + +!!! warn + This endpoint excludes achieved targets -- targets still get interacted with when achieved, which means a user with a lot of targets will just flood this endpoint with redundant updates on larger imports. + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `goals` | Array<GoalDocument> | The goal documents that were recently achieved. | +| `milestones` | Array<MilestoneDocument> | The milestone documents that were recently achieved. | +| `goalSubs` | Array<GoalSubDocument> | User subscriptions to goals that were recently interacted with. | +| `milestoneSubs` | Array<MilestoneSubDocument> | User subscriptions to milestones that were recently interacted with. | + +### Example + +#### Request +``` +GET /api/v1/games/iidx/SP/targets/recently-interacted +``` + +#### Response + +```js +{ + goals: [{ + name: "HARD CLEAR 5.1.1 Another", + goalID: "foo" + // ... other goal props + }], + milestones: [{ + name: "Go Beyond Diamond 1", + milestoneID: "bar", + // ... other milestone props + }], + goalSubs: [{ + userID: 1, + goalID: "foo", + achieved: false, + lastInteraction: 1649438990417, + // ... other goalsub props + }], + milestoneSubs: [{ + userID: 3, + milestoneID: "bar", + achieved: false, + lastInteraction: 1649438990415, + // ... other milestone sub props + }] +} +``` + +***** + +## Get the most popular goals for this GPT. + +`GET /api/v1/games/:game/:playtype/targets/goals/popular` + +### Parameters + +N/A + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `` | Array<GoalDocument & `__subscriptions` > | An array of the 100 most popular goals for this GPT, where `__subscriptions` is how many subscriptions the goal has. | + +### Example + +#### Request +``` +GET /api/v1/games/:game/:playtype/targets/goals?search=foo +``` + +#### Response + +```js +[{ + name: "HARD CLEAR foo", + // ... +}, { + name: "AAA foo", + // ... +}] +``` + +***** + +## Retrieve information about a specific goal and its subscribers + +`GET /api/v1/games/:game/:playtype/targets/goals/:goalID` + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `goal` | GoalDocument | The goal document at this ID. | +| `goalSubs` | Array<GoalSubDocument> | All of the subscriptions to this goal. | +| `users` | Array<UserDocument> | All of the users subscribed to this goal. | + +***** + +## Evaluate a goal upon a user. + +`GET /api/v1/games/:game/:playtype/targets/goals/:goalID/evaluate-for` + +!!! note + This endpoint is notably in a bit of a strange position. It can't go under UGPT because + `UGPT/goals/:goalID` is for goal subscriptions, and overloading the endpoint to be + something like "return the goal subscription or evaluate it if doesn't exist" is ugly. + + As such, it ends up here, but is generally a bit awkward. + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `userID` | String | The user to evaluate this goal for. | + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `goal` | GoalDocument | The goal document that was evaluated. | +| `user` | UserDocument | The user that this goal was evaluated for. | +| `results.achieved` | Boolean | Whether this user would have this goal achieved or not. | +| `results.progress` | Integer | What this user's progress would be on this goal. | +| `results.progressHuman` | String | A user friendly format for this user's goal progress. | +| `results.outOf` | Integer | What this goal was out of. | +| `results.outOfHuman` | String | A user friendly format for what this goal was out of. | + +!!! info + For more info on `progress`/`outOf`, see [Goals](../../tachi-server/implementation-details/goals-milestones.md#evaluating-a-users-progress). + +### Example + +#### Request +``` +GET /api/v1/games/iidx/SP/targets/goals/some_goal_id/evaluate-for?userID=zkldi +``` + +#### Response + +```js +{ + user: { + username: "zkldi", + id: 1, + // ... + }, + goal: { + goalID: "some_goal_id", + name: "FULL COMBO some chart" + // ... + }, + result: { + achieved: false, + progress: 5, + progressHuman: "EX HARD CLEAR", + outOf: 6, + outOfHuman: "FULL COMBO" + } +} +``` + +!!! info + Searching goals for a GPT isn't very interesting, since they can be created by anyone at any time. The only reason goals are stored separately to subscriptions are for deduplication purposes and milestones. + + As such, searching goals for a GPT is pointless, since technically it should search the set of all possible goals. \ No newline at end of file diff --git a/docs/docs/api/routes/gpt.md b/docs/docs/api/routes/gpt.md index e2b5ac106..024222a82 100644 --- a/docs/docs/api/routes/gpt.md +++ b/docs/docs/api/routes/gpt.md @@ -601,7 +601,7 @@ GET /api/v1/games/bms/7K/player-distribution?class=stslDan | Property | Type | Description | | :: | :: | :: | -| `limit` | Optional Integer | Optionally, provide an integer between 1 and 100 to return this amount of scores. Defaults to 10. | +| `limit` | Optional Integer | Optionally, provide an integer between 1 and 100 to return this amount of scores. Defaults to 100. | ### Response diff --git a/docs/docs/tachi-server/documents/chart.md b/docs/docs/tachi-server/documents/chart.md index 012c9a947..726020bd9 100644 --- a/docs/docs/tachi-server/documents/chart.md +++ b/docs/docs/tachi-server/documents/chart.md @@ -30,7 +30,7 @@ interface ChartDocument { | `songID` | The corresponding parent [Song Document](./song.md)'s ID. | | `level` | A string representing the level for this chart. This is a string because games use identifiers like '12+'. | | `levelNum` | A number representing the level for this chart. This may be a decimal. | -| `isPrimary` | Whether this chart is primary or not. For more information on this, see [isPrimary](songs-../implementation-details/songs-charts.md#isPrimary) +| `isPrimary` | Whether this chart is primary or not. For more information on this, see [isPrimary](../implementation-details/songs-charts.md#isPrimary) `difficulty` | A string representing what difficulty this chart is for. The valid values for this field depend on the GPT. | | `playtype` | What playtype this chart is for. | | `data` | Additional GPT Specific data about this chart, such as inGameIDs or SHA hashes. | diff --git a/docs/docs/tachi-server/documents/goal.md b/docs/docs/tachi-server/documents/goal.md index 2cfcc0757..ab291c6e1 100644 --- a/docs/docs/tachi-server/documents/goal.md +++ b/docs/docs/tachi-server/documents/goal.md @@ -4,8 +4,8 @@ Goals are stored in `goals`. !!! warning This document describes a goal, but does not describe - a user's "subscription" to that goal. For that, see - [User Goal Document](./user-goal.md). + a user's "subscription" to that goal. For that, see the + [Goal Subscription Document](./goal-sub.md). ***** diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index a9e95beae..faee266fa 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -64,6 +64,7 @@ nav: - "api/routes/oauth2.md" - "api/routes/clients.md" - "api/routes/config.md" + - "api/routes/gpt-targets.md" - Webhooks: - "api/webhooks/main.md" @@ -85,6 +86,7 @@ nav: - "tachi-server/infrastructure/api-clients.md" - "tachi-server/infrastructure/oauth2.md" - "tachi-server/infrastructure/file-flow.md" + - "tachi-server/infrastructure/database-seeds.md" - Structure: - "tachi-server/structure/style.md" @@ -120,6 +122,7 @@ nav: - "tachi-server/implementation-details/esd.md" - "tachi-server/implementation-details/score-id.md" - "tachi-server/implementation-details/goal-id.md" + - "tachi-server/implementation-details/goals-milestones.md" - Documents: - "tachi-server/documents/overview.md"