zk
e363bd2532
* docs: migrate from mkdocs to mdbook - Rename old mkdocs docs/ to old-docs/ for reference - Set up new docs/ with mdbook (book.toml + src/ tree) - Mirror full nav structure from mkdocs.yml into SUMMARY.md - Add Justfile-docs with docs-serve, docs-build, docs-check, docs-install recipes - Import Justfile-docs from root Justfile - Rewrite .github/workflows/docs.yml: build step uses taiki-e/install-action to install mdbook, split into separate build + deploy jobs, PR builds run the check step too * ci(docs): pin actions to SHAs, install mdbook via release binary * ci(docs): install mdbook from apt instead of curling a release binary * dev: replace mkdocs python stack with mdbook in dev image * ci(docs): apt only works on Debian; restore release binary install for Ubuntu CI * docs: fix duplicate file entries in SUMMARY.md * docs: remove docs-install recipe * docs: remove site-url from book.toml to fix asset loading * dev: install mdbook from upstream release binary, not Debian apt The Debian package (0.4.x+ds) strips bundled font assets, leaving the built site without fonts/fonts.css. Use the upstream tarball (same as CI) so the theme is complete. Handles x86_64 and aarch64. * docs: vendor mdbook tarballs in dev/mdbook/, install from there Dockerfile.dev uses COPY + tar to install the right arch at build time. CI extracts the x86_64 tarball directly from the checkout. No network access required for either — and no stripped-fonts Debian package. * fix: unwritten
4.9 KiB
UGPT-Target Endpoints
These endpoints deal with targets for a User, Game and Playtype. These are things like subscribing to a new quest, or reading info about progress on a specific goal.
For user-specific target endpoints, such as subscriptions, see UGPT-Target Endpoints.
Retrieve a user's recently achieved targets.
GET /api/v1/users/:userID/games/:gameGroup/: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). |
| questSubs | Array<QuestSubDocument> | The quest subscriptions that were recently achieved by this user. |
| quest | Array<QuestDocument> | The quest 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/:gameGroup/: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). |
| questSubs | Array<QuestSubDocument> | The quest subscriptions that were recently achieved by this user. |
| quest | Array<QuestDocument> | The quest documents that were recently achieved (if any). |
| user | UserDocument | The user you requested this information about. |
Retrieve this user's quest subscriptions.
GET /api/v1/users/:userID/games/:gameGroup/:playtype/targets/quests
Parameters
None.
Response
| Property | Type | Description |
| :: | :: | :: |
| quests | Array<QuestDocument> | All of the quests this user is subscribed to. |
| questSubs | Array<QuestSubDocument> | All of this user's quest subscriptions. |
Get a user's progress on a specific quest they are subscribed to.
GET /api/v1/users/:userID/games/:gameGroup/:playtype/targets/quests/:questID
!!! info If you're looking to evaluate a quest against a user, without knowing whether they're subscribed to it or not, you want GPT/Targets/Quests/Evaluate-For.
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 `questSub`, so I thought it best to split this into two endpoints.
Parameters
None.
Response
| Property | Type | Description |
| :: | :: | :: |
| questSub | QuestSubDocument | The user's subscription to this quest. |
| quest | QuestDocument | The quest document in question. |
| goals | Array<GoalDocument> | The goals involved in this quest. |
| results | Array<EvaluatedGoalResult> | The user's progress on each goal in this quest. |
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 quest.
PUT /api/v1/users/:userID/games/:gameGroup/:playtype/targets/quests/:questID
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 quest. |
| quest | QuestDocument | The quest the user just subscribed to. |
| goalResults | Array<EvaluatedGoalResults> | The user's progress on each individual goal in this quest. |
| questSub | QuestSubscriptionDocument | The quest subscription this user just created |
Unsubscribe from a quest.
DELETE /api/v1/users/:userID/games/:gameGroup/:playtype/targets/quests/:questID
Permissions
manage_targets- Must be the requesting user.
Parameters
None.
Response
| Property | Type | Description |
| :: | :: | :: |
| quest | QuestDocument | The quest you just unsubscribed from. |