diff --git a/docs/docs/api/routes/ugpt-targets.md b/docs/docs/api/routes/ugpt-targets.md new file mode 100644 index 000000000..96194f7e7 --- /dev/null +++ b/docs/docs/api/routes/ugpt-targets.md @@ -0,0 +1,148 @@ +# UGPT-Target Endpoints + +These endpoints deal with [targets](../../api/terminology.md) for a User, Game and Playtype. These are things like subscribing to a new milestone, or reading info about progress on a specific goal. + +For user-specific target endpoints, such as subscriptions, see [UGPT-Target Endpoints](./ugpt-targets.md). + +***** + +***** + +## Retrieve a user's recently achieved targets. + +`GET /api/v1/users/:userID/games/:game/:playtype/targets/recently-achieved` + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `goalSubs` | Array<GoalSubDocument> | The goal subscriptions that were recently achieved by this user. | +| `goals` | Array<GoalDocument> | The goal documents that were recently achieved (if any). | +| `milestoneSubs` | Array<MilestoneSubDocument> | The milestone subscriptions that were recently achieved by this user. | +| `milestone` | Array<MilestoneDocument> | The milestone documents that were recently achieved (if any). | +| `user` | UserDocument | The user you requested this information about. | + +***** + +## Retrieve a user's recently raised targets. + +`GET /api/v1/users/:userID/games/:game/:playtype/targets/recently-raised` + +!!! info + Recently raised means that the user recently increased their `progress` on the target. It explicitly excludes achieved goals -- only things that they are getting closer to. + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `goalSubs` | Array<GoalSubDocument> | The goal subscriptions that were recently achieved by this user. | +| `goals` | Array<GoalDocument> | The goal documents that were recently achieved (if any). | +| `milestoneSubs` | Array<MilestoneSubDocument> | The milestone subscriptions that were recently achieved by this user. | +| `milestone` | Array<MilestoneDocument> | The milestone documents that were recently achieved (if any). | +| `user` | UserDocument | The user you requested this information about. | + +***** + +## Retrieve this user's milestone subscriptions. + +`GET /api/v1/users/:userID/games/:game/:playtype/targets/milestones` + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `milestones` | Array<MilestoneDocument> | All of the milestones this user is subscribed to. | +| `milestoneSubs` | Array<MilestoneSubDocument> | All of this user's milestone subscriptions. | + +***** + +## Get a user's progress on a specific milestone they are subscribed to. + +`GET /api/v1/users/:userID/games/:game/:playtype/targets/milestones/:milestoneID` + +!!! info + If you're looking to evaluate a milestone against a user, without knowing whether they're + subscribed to it or not, you want [GPT/Targets/Milestones/Evaluate-For](gpt-targets.md#evaluate-a-milestone-for-a-user-even-if-they-arent-subscribed-to-it). + + This endpoint is admittedly in a very strange position, where it overlaps with that `evaluate-for` endpoint quite significantly, but this endpoint is also intended to return the user's `milestoneSub`, so I thought it best to split this into two endpoints. + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `milestoneSub` | MilestoneSubDocument | The user's subscription to this milestone. | +| `milestone` | MilestoneDocument | The milestone document in question. | +| `goals` | Array<GoalDocument> | The goals involved in this milestone. | +| `results` | Array<EvaluatedGoalResult> | The user's progress on each goal in this milestone. | + +#### EvaluatedGoalResult + +| Property | Type | Description | +| :: | :: | :: | +| `goalID` | String | The goal ID that these results are for. | +| `achieved` | Boolean | Whether this goal was achieved or not. | +| `progress` | Number \| Null | How much progress this user made on this goal. Null if no progress was made. | +| `outOf` | Number | What `progress` needs to be greater than or equal to for this goal to count as achieved. | +| `progressHuman` | String | A humanised, pretty-printed progress indicator for this goal. | +| `outOfHuman` | String | A humanised, pretty-printed outOf indicator for this goal. | + +***** + +## Subscribe to a milestone. + +`PUT /api/v1/users/:userID/games/:game/:playtype/targets/milestones/:milestoneID` + +### Permissions + +- `manage_targets` +- Must be the requesting user. + +### Parameters + +None. (All relevant info is in the URL.) + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `goals` | Array<GpalDocument> | The goals involved in this milestone. | +| `milestone` | MilestoneDocument | The milestone the user just subscribed to. | +| `goalResults` | Array<EvaluatedGoalResults> | The user's progress on each individual goal in this milestone. | +| `milestoneSub` | MilestoneSubscriptionDocument | The milestone subscription this user just created | + +***** + +## Unsubscribe from a milestone. + +`DELETE /api/v1/users/:userID/games/:game/:playtype/targets/milestones/:milestoneID` + +### Permissions + +- `manage_targets` +- Must be the requesting user. + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `milestone` | MilestoneDocument | The milestone you just unsubscribed from. | diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index faee266fa..23de9538a 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -65,6 +65,7 @@ nav: - "api/routes/clients.md" - "api/routes/config.md" - "api/routes/gpt-targets.md" + - "api/routes/ugpt-targets.md" - Webhooks: - "api/webhooks/main.md"