From f0b7b25d18bed16cfb152bb147e5b52deec1ec62 Mon Sep 17 00:00:00 2001 From: zkldi Date: Sat, 26 Jun 2021 02:40:15 +0100 Subject: [PATCH 01/12] clarify what makes r3 different from r1 --- docs/docs/user/rules.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/docs/user/rules.md b/docs/docs/user/rules.md index 25c86503a..4c9e2d08b 100644 --- a/docs/docs/user/rules.md +++ b/docs/docs/user/rules.md @@ -72,6 +72,7 @@ The valid input devices are listed below. ### Bokutachi | Game | Devices | Justifications | +| :: | :: | :: | | unnamed_sdvx_clone | Same as SDVX | Keyboard play is not allowed, etc. | | BMS (7K) | Keyboard, any IIDX Controller | Keyboard play is allowed for BMS 7K. | | BMS (14K) | any two IIDX Controllers | Keyboard play is **NOT** allowed for BMS 14K. | @@ -83,8 +84,9 @@ This rule is depressing to write, but it has to be said. This rule exists to make sure that the Tachi community is filled with good people, and that bad actors do not have -a platform to be legitimised further. This rule covers -interactions **outside of Tachi**, which includes, **but is not limited to**: +a platform to be legitimised further. Unlike the civility +rule, This rule covers interactions **outside of Tachi**, +which includes, **but is not limited to**: - Assault of other community members (Physical, Sexual etc.). - Relationships with minors (When the offender is an adult of unreasonable age). @@ -112,13 +114,11 @@ interactions **outside of Tachi**, which includes, **but is not limited to**: stupid.) - Not liking another community member. - - ## You are only allowed one account. Do not make multiple accounts, we track account IPs and it -let's us know. This is to keep the leaderboards fair -and avoid one player from taking multiple spaces. +lets us know. This is to keep the leaderboards fair +and avoid one player from taking up multiple spaces. ## Do not set NSFW artwork as your avatar or banner. From aeb1c4e3e265f96566a068f744e3cd59b3211098 Mon Sep 17 00:00:00 2001 From: zkldi Date: Sat, 26 Jun 2021 02:40:41 +0100 Subject: [PATCH 02/12] remove tachi_parallel_tests as it was dangerous --- docs/docs/codebase/setup/config.md | 18 ------------------ 1 file changed, 18 deletions(-) diff --git a/docs/docs/codebase/setup/config.md b/docs/docs/codebase/setup/config.md index be39c55db..e8f263f9b 100644 --- a/docs/docs/codebase/setup/config.md +++ b/docs/docs/codebase/setup/config.md @@ -134,21 +134,3 @@ names. "omni" will run the server without any route restrictions. This is used for testing. - -## Environment Variables - -### TACHI_PARALLEL_TESTS - -If this is set and `tap` is invoked, this will change some -things about the environment to support running multiple -tests at once. - -!!! warning - This will ruin your MongoDB installation with lots of - ephemeral collections. Do not run this on a local - setup. - - This is intended for Github Actions' runner, which is - designed to quickly start up and then tear everything - down afterwards. - From 9c51f3a45f163fb4b1d38db4ea85ebea875db6ed Mon Sep 17 00:00:00 2001 From: zkldi Date: Sat, 26 Jun 2021 02:44:37 +0100 Subject: [PATCH 03/12] add cdn_url to conf.json5 --- docs/docs/codebase/setup/config.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/docs/codebase/setup/config.md b/docs/docs/codebase/setup/config.md index e8f263f9b..40ad156ec 100644 --- a/docs/docs/codebase/setup/config.md +++ b/docs/docs/codebase/setup/config.md @@ -113,6 +113,21 @@ We use an ARC session token in order to pull scores from `ARC`. The session toke and profile pictures. This is a folder somewhere on the system (presumably using nginx serve-static). +### CDN_URL + +- Type: URL or null (Optional). + +This parameter dictates where the CDN server is. Requests that hit the CDN +will be redirected here. If null, or not present, `tachi-server` will use +filesystem calls for the files (and return them) instead of redirects. + +!!! note + Nginx Serve-Static is relatively easy to set up, and provides + massive performance increases for this kind of stufff. + + I highly recommend against leaving this null, as you can cause + large performance deficits. + ### PORT - Type: Port (1-65536) From 951aff62606b628a2135ef543a262c181e13ceb6 Mon Sep 17 00:00:00 2001 From: zkldi Date: Mon, 28 Jun 2021 13:51:38 +0100 Subject: [PATCH 04/12] search and session documentation --- docs/docs/api/routes/search.md | 52 ++++++++ docs/docs/api/routes/sessions.md | 116 ++++++++++++++++++ docs/docs/api/routes/users.md | 6 +- .../codebase/implementation-details/search.md | 19 ++- docs/mkdocs.yml | 4 +- 5 files changed, 192 insertions(+), 5 deletions(-) create mode 100644 docs/docs/api/routes/search.md create mode 100644 docs/docs/api/routes/sessions.md diff --git a/docs/docs/api/routes/search.md b/docs/docs/api/routes/search.md new file mode 100644 index 000000000..2e4f46202 --- /dev/null +++ b/docs/docs/api/routes/search.md @@ -0,0 +1,52 @@ +# Search Endpoints + +***** + +## Search Everything + +`GET /api/v1/search` + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `search` | string | What to search for. | + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `users` | UserDocument[] | The array of users whose usernames look like the search criterion. | +| `songs` | (SongDocument With [__textScore](../../codebase/implementation-details/search.md) and `game`.)[] | An array of songs from all games, with `__textScore` and `game` properties attached. | + +### Example + +#### Request +``` +GET /api/v1/search?search=freedom +``` + +#### Response + +```js +{ + users: [{ + username: "FreedomDiver", + // ... + }], + songs: [{ + title: "FREEDOM", + __textScore: 2, + game: "iidx", + // ... + }, { + title: "FREEDOM DiVE", + __textScore: 1, + game: "bms", + // ... + }] +} +``` + +!!! info + For more details on how searching works, see [Search Implementation](../../codebase/implementation-details/search.md). \ No newline at end of file diff --git a/docs/docs/api/routes/sessions.md b/docs/docs/api/routes/sessions.md new file mode 100644 index 000000000..89cda6f55 --- /dev/null +++ b/docs/docs/api/routes/sessions.md @@ -0,0 +1,116 @@ +# Session Endpoints + +***** + +## Get a specific session + +`GET /api/v1/sessions/:sessionID` + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `session` | SessionDocument | The session document at this ID. | +| `scores` | ScoreDocument[] | The score documents involved in this session. | +| `songs` | SongDocument[] | The songs these score documents belong to. | +| `charts` | ChartDocument[] | The charts these score documents belong to. | +| `user` | UserDocument | The user that made this session. | + +### Example + +#### Request +``` +GET /api/v1/sessions/Qe7b00261b1d3ba8e5c9ee4e76e77ea9f07d9493b +``` + +#### Response + +```js +{ + user: { + id: 1, + username: "zkldi", + // ... + }, + session: { + sessionID: "Qe7b00261b1d3ba8e5c9ee4e76e77ea9f07d9493b", + scores: [{ + scoreID: "foo", + // ... + }], + name: "my session", + // ... + }, + scores: [{ + scoreID: "foo", + songID: 1, + chartID: "foo_chartID", + }], + songs: [{ + id: 1, + // ... + }], + charts: [{ + chartID: "foo_chartID", + songID: 1 + // ... + }] +} +``` + +***** + +## Modify a session + +`PATCH /api/v1/sessions/:sessionID` + +### Permissions + +- customise_session +- Must be the owner of this session. + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `name` (optional) | String | A new name for this session. This must be between 3 and 80 characters. If not present, no update will be made to the session name. | +| `desc` (optional) | String | A new description for this session. This must be between 3 and 120 characters. If not present, no update to the description will be made. | +| `highlight` (optional) | boolean | Whether this session is highlighted or not. If not present, no change will be made to the highlighted status. | + +!!! info + Although all these fields are optional, making a request + without any of them is a 400 error. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `` | SessionDocument | The new session document, after modifications. | + +### Example + +#### Request +``` +PATCH /api/v1/sessions/Qe7b00261b1d3ba8e5c9ee4e76e77ea9f07d9493b +``` + +```json +{ + "name": "new session name", +} +``` + +#### Response + +```json +{ + "name": "new session name", + "desc": "old session desc", + "highlighted": false + // ... +} +``` \ No newline at end of file diff --git a/docs/docs/api/routes/users.md b/docs/docs/api/routes/users.md index 6aa2c0fd8..6b3540154 100644 --- a/docs/docs/api/routes/users.md +++ b/docs/docs/api/routes/users.md @@ -13,7 +13,7 @@ These endpoints are related to users in general. | Property | Type | Description | | :: | :: | :: | | `online` (Optional) | Presence | If present, this limits the returned users to those that are currently online. | -| `username` (Optional) | String | If present, this endpoint works like a search engine for usernames. Users will be returned in their proximity to the original text. | +| `search` (Optional) | String | If present, this endpoint will only return users where this string is contained within their username. | ### Response @@ -33,7 +33,7 @@ GET /api/v1/users ```js [{ - "userID": 1, + "id": 1, "username": "zkldi", // ... continued }] @@ -76,7 +76,7 @@ GET /api/v1/users/1 ```js { - userID: 1, + id: 1, username: "zkldi", // ... so on } diff --git a/docs/docs/codebase/implementation-details/search.md b/docs/docs/codebase/implementation-details/search.md index 2427c21b2..f4de0bbe7 100644 --- a/docs/docs/codebase/implementation-details/search.md +++ b/docs/docs/codebase/implementation-details/search.md @@ -23,4 +23,21 @@ This is sometimes exposed in the API for sorting reasons. Regex has performance issues on larger datasets and we want to avoid it. Most regexes cannot use indexes, and therefore invoke a COLLSCAN, which - we want to avoid. \ No newline at end of file + we want to avoid. + +## User Searching + +Searching users, on the other hand, has to use regex-based +searching. + +The `$text` method attempts to break things up based on their +words, but that doesn't help with usernames, as they are all +too frequently `XxX_One_Long_Str1ng_xXx`. + +Instead, we use a case insensitive regex - similar to SQL's +`LIKE`. + +This means we do not have a `__textScore` property for this +search to sort on. Instead, we just constrict returns to +around 15, and have the user whittle their search down +better. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index fd5ccbba8..b15b34609 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,7 +1,7 @@ site_name: Tachi Documentation site_description: Mono-documentation for Kamaitachi, Bokutachi and related things. site_author: zkldi -site_url: https://docs.bokutachi.xyz +site_url: https://tachi.rtfd.io theme: name: material @@ -49,6 +49,8 @@ nav: - "api/routes/auth.md" - "api/routes/users.md" - "api/routes/user-gamept.md" + - "api/routes/sessions.md" + - "api/routes/search.md" - Codebase Reference: - "codebase/overview.md" From 50c95ae5a31887a1e421aa49f5660412768a16e4 Mon Sep 17 00:00:00 2001 From: zkldi Date: Mon, 28 Jun 2021 13:59:22 +0100 Subject: [PATCH 05/12] add score api documentation --- docs/docs/api/routes/scores.md | 105 +++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 docs/docs/api/routes/scores.md diff --git a/docs/docs/api/routes/scores.md b/docs/docs/api/routes/scores.md new file mode 100644 index 000000000..c6dd9a086 --- /dev/null +++ b/docs/docs/api/routes/scores.md @@ -0,0 +1,105 @@ +# Score Endpoints + +!!! note + Scores are *not* personal bests. For more information + on the distinction, see [Something](todo). + +***** + +## Retrieve specific score. + +`GET /api/v1/scores/:scoreID` + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `getRelated` | Presence | If present, also return the song and chart for this score document. | + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `score` | ScoreDocument | The score document with this scoreID. | +| `song` (Conditional) | SongDocument | If `getRelated` is set, then this is the song the score belongs to. | +| `chart` (Conditional) | ChartDocument | Same as above, but for the chart document. | + +### Example + +#### Request +``` +GET /api/v1/scores/Re7b00261b1d3ba8e5c9ee4e76e77ea9f07d9493b +``` + +#### Response + +```json +{ + "score": { + "scoreID": "Re7b00261b1d3ba8e5c9ee4e76e77ea9f07d9493b", + "songID": 1, + "chartID": "some_chart_ID" + }, + "song": { + "id": 1, + "title": "5.1.1." + }, + "chart": { + "chartID": "some_chartID", + "songID": 1 + } +} +``` + +***** + +## Modify a score document + +`PATCH /api/v1/scores/:scoreID` + +### Permissions + +- customise_score +- Must be the owner of this score. + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `comment` (Optional) | Null or String | A string between 1 and 120 characters, or null. If null, the score will have its comment unset. If not, the comment for this score will be set to its contents. If the key is not present, no change will be made. | +| `highlight` (Optional) | Boolean | Whether this score was a highlight or not. If this field is not present, no change will be made to the highlight status. | + +!!! info + Although all of these fields are optional, providing none + of them is a 400 failure. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `` | ScoreDocument | The new score document. + +### Example + +#### Request +``` +PATCH /api/v1/scores/Re7b00261b1d3ba8e5c9ee4e76e77ea9f07d9493b +``` + +```json +{ + "comment": "new comment" +} +``` + +#### Response + +```json +{ + "scoreID": "Re7b00261b1d3ba8e5c9ee4e76e77ea9f07d9493b", + "comment": "new comment", + "highlighted": false, + // etc.. +} + +``` \ No newline at end of file From e7660e3aa414b6ce29455d63d9c3b3efe10846e0 Mon Sep 17 00:00:00 2001 From: zkldi Date: Mon, 28 Jun 2021 16:28:50 +0100 Subject: [PATCH 06/12] add highlighted endpoint --- docs/docs/api/routes/user-gamept.md | 46 +++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/docs/api/routes/user-gamept.md b/docs/docs/api/routes/user-gamept.md index ad7cfd356..39ec45dfa 100644 --- a/docs/docs/api/routes/user-gamept.md +++ b/docs/docs/api/routes/user-gamept.md @@ -526,4 +526,50 @@ GET /api/v1/users/zkldi/games/iidx/SP/sessions/best } } ] +``` + +## Get a user's most recent 100 highlighted sessions. + +`GET /api/v1/users/:userID/games/:game/:playtype/sessions/highlighted` + +Retrieves a user's most recent 100 highlighted sessions for this game. + +These are returned in descending order according to `timeEnded`. + +### Parameters + +| 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 + +| Property | Type | Description | +| :: | :: | :: | +| `` | Array<SessionDocument> | The array of the users highlighted sessions. | + +### Example + +#### Request +``` +GET /api/v1/users/zkldi/games/iidx/SP/sessions/highlighted +``` + +#### Response + +```js +[ + { + userID: 1, + game: "iidx", + playtype: "SP", + calculatedData: { + ktRating: 14, + bpi: 3 + } + highlight: true + }, +] ``` \ No newline at end of file From b955f825f8aa1b5dd8423d562130dec80a67efa5 Mon Sep 17 00:00:00 2001 From: zkldi Date: Mon, 28 Jun 2021 16:33:58 +0100 Subject: [PATCH 07/12] add pbs/:chartID --- docs/docs/api/routes/user-gamept.md | 47 +++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/docs/api/routes/user-gamept.md b/docs/docs/api/routes/user-gamept.md index 39ec45dfa..bec0edc30 100644 --- a/docs/docs/api/routes/user-gamept.md +++ b/docs/docs/api/routes/user-gamept.md @@ -301,6 +301,53 @@ GET /api/v1/users/zkldi/games/iidx/SP/pbs/best?alg=BPI ***** +## Get A User's PB for a given chart. + +`GET /api/v1/users/:userID/games/:game/:playtype/pbs/:chartID` + +### Parameters + +| 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 + +| Property | Type | Description | +| :: | :: | :: | +| `pb` | PBDocument | The user's PB for this chart. | +| `chart` | ChartDocument | The chart this PB is on. | +| `scores` (Conditional) | ScoreDocument[] | If `getComposition` is present, then this field contains the array of score documents that composed this PB. | + +### Example + +#### Request +``` +GET /api/v1/users/1/games/iidx/SP/pbs/some_chart_id +``` + +#### Response + +```js +{ + pb: { + chartID: "some_chart_id", + userID: 1, + game: "iidx", + playtype: "SP", + }, + chart: { + chartID: "some_chart_id" + } +} +``` + +***** + ## Search a user's individual scores. `GET /api/v1/users/:userID/games/:game/:playtype/scores` From b8aeaabf88b25ed675edb797b00dd9af2c320e57 Mon Sep 17 00:00:00 2001 From: zkldi Date: Mon, 28 Jun 2021 16:41:16 +0100 Subject: [PATCH 08/12] document `me` --- docs/docs/api/routes/user.md | 70 +++++++++++++++++++++++++++++++++++ docs/docs/api/routes/users.md | 13 +++++++ 2 files changed, 83 insertions(+) create mode 100644 docs/docs/api/routes/user.md diff --git a/docs/docs/api/routes/user.md b/docs/docs/api/routes/user.md new file mode 100644 index 000000000..1d37b34d3 --- /dev/null +++ b/docs/docs/api/routes/user.md @@ -0,0 +1,70 @@ +# Individual User Endpoints + +***** + +## Change Profile Picture + +`PUT /api/v1/users/:userID/pfp` + +### Permissions + +- customise_profile +- Must be the owner of this profile. + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `pfp` | JPG, or PNG | The new profile picture to set. | + +!!! note + This endpoint expects multipart form data. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `get` | String | This contains the URL to then GET the new profile picture. | + +### Example + +#### Request +``` +PUT /api/v1/users/1/pfp +``` + +``` +// this is not a real multipart request, as those things +// are huge! +pfp= +``` + +#### Response + +```json +{ + "get": "/api/v1/users/1/pfp" +} +``` + +***** + +## Get a user's profile picture. + +`GET /api/v1/users/:userID/pfp` + +### Parameters + +None. + +### Response + +Not JSON. This returns the actual JPG or PNG stored for +this user. + +### Example + +N/A + + + diff --git a/docs/docs/api/routes/users.md b/docs/docs/api/routes/users.md index 6b3540154..ae1ea85da 100644 --- a/docs/docs/api/routes/users.md +++ b/docs/docs/api/routes/users.md @@ -51,6 +51,17 @@ GET /api/v1/users | :: | :: | :: | | `:userID` | URL Parameter | The user's userID or their username. | +!!! note + The :userID param has some special functionality, + and any time you see it in these docs, that + functionality is supported. + + You may pass the integer userID for this user - 1. + You may also pass the username - zkldi. + You may also pass the special string - `me` - which + will select whatever user this authentication token + is for. + ### Response | Property | Type | Description | @@ -70,6 +81,8 @@ GET /api/v1/users GET /api/v1/users/zkldi OR GET /api/v1/users/1 +OR +GET /api/v1/users/me WHEN authenticated as userID 1. ``` #### Response From f00be31b93d33afd685da334f5de37fb14e547aa Mon Sep 17 00:00:00 2001 From: zkldi Date: Mon, 28 Jun 2021 16:47:24 +0100 Subject: [PATCH 09/12] add pfp and banner endpoints --- docs/docs/api/routes/user.md | 70 ------------- docs/docs/api/routes/users.md | 188 ++++++++++++++++++++++++++++++++++ 2 files changed, 188 insertions(+), 70 deletions(-) delete mode 100644 docs/docs/api/routes/user.md diff --git a/docs/docs/api/routes/user.md b/docs/docs/api/routes/user.md deleted file mode 100644 index 1d37b34d3..000000000 --- a/docs/docs/api/routes/user.md +++ /dev/null @@ -1,70 +0,0 @@ -# Individual User Endpoints - -***** - -## Change Profile Picture - -`PUT /api/v1/users/:userID/pfp` - -### Permissions - -- customise_profile -- Must be the owner of this profile. - -### Parameters - -| Property | Type | Description | -| :: | :: | :: | -| `pfp` | JPG, or PNG | The new profile picture to set. | - -!!! note - This endpoint expects multipart form data. - -### Response - -| Property | Type | Description | -| :: | :: | :: | -| `get` | String | This contains the URL to then GET the new profile picture. | - -### Example - -#### Request -``` -PUT /api/v1/users/1/pfp -``` - -``` -// this is not a real multipart request, as those things -// are huge! -pfp= -``` - -#### Response - -```json -{ - "get": "/api/v1/users/1/pfp" -} -``` - -***** - -## Get a user's profile picture. - -`GET /api/v1/users/:userID/pfp` - -### Parameters - -None. - -### Response - -Not JSON. This returns the actual JPG or PNG stored for -this user. - -### Example - -N/A - - - diff --git a/docs/docs/api/routes/users.md b/docs/docs/api/routes/users.md index ae1ea85da..b67a142ac 100644 --- a/docs/docs/api/routes/users.md +++ b/docs/docs/api/routes/users.md @@ -151,3 +151,191 @@ GET /api/v1/users/1/stats !!! info In the event a user has played no games, this will return an empty array. + +***** + +## Change Profile Picture + +`PUT /api/v1/users/:userID/pfp` + +### Permissions + +- customise_profile +- Must be the owner of this profile. + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `pfp` | JPG, or PNG | The new profile picture to set. | + +!!! note + This endpoint expects multipart form data. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `get` | String | This contains the URL to then GET the new profile picture. | + +### Example + +#### Request +``` +PUT /api/v1/users/1/pfp +``` + +``` +// this is not a real multipart request, as those things +// are huge! +pfp= +``` + +#### Response + +```json +{ + "get": "/api/v1/users/1/pfp" +} +``` + +***** + +## Get a user's profile picture. + +`GET /api/v1/users/:userID/pfp` + +### Parameters + +None. + +### Response + +Not JSON. This returns the actual JPG or PNG stored for +this user. + +### Example + +N/A + +***** + +***** + +## Unset your profile picture. + +`DELETE /api/v1/users/:userID/pfp` + +!!! note + If you do not have a profile picture set, this is + a 404 error. + +### Permissions + +- customise_profile +- Must be the owner of this profile. + +### Parameters + +None. +### Response + +None. + +### Example + +Self-explanatory. + +***** + +## Change Profile Banner + +`PUT /api/v1/users/:userID/banner` + +### Permissions + +- customise_profile +- Must be the owner of this profile. + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `banner` | JPG, or PNG | The new profile banner to set. | + +!!! note + This endpoint expects multipart form data. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `get` | String | This contains the URL to then GET the new profile banner. | + +### Example + +#### Request +``` +PUT /api/v1/users/1/banner +``` + +``` +// this is not a real multipart request, as those things +// are huge! +banner= +``` + +#### Response + +```json +{ + "get": "/api/v1/users/1/banner" +} +``` + +***** + +## Get a user's profile banner. + +`GET /api/v1/users/:userID/banner` + +### Parameters + +None. + +### Response + +Not JSON. This returns the actual JPG or PNG stored for +this user. + +### Example + +N/A + +***** + +***** + +## Unset your profile banner. + +`DELETE /api/v1/users/:userID/banner` + +!!! note + If you do not have a profile banner set, this is + a 404 error. + +### Permissions + +- customise_profile +- Must be the owner of this profile. + +### Parameters + +None. +### Response + +None. + +### Example + +Self-explanatory. From 6f7eaa4068d4fbcbfedf5e60750e5eb3768d1c50 Mon Sep 17 00:00:00 2001 From: zkldi Date: Mon, 28 Jun 2021 16:51:45 +0100 Subject: [PATCH 10/12] add whoami to status --- docs/docs/api/routes/status.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docs/api/routes/status.md b/docs/docs/api/routes/status.md index 29306a122..fe951e049 100644 --- a/docs/docs/api/routes/status.md +++ b/docs/docs/api/routes/status.md @@ -24,6 +24,7 @@ It's a good way of sanity checking whether your code works. | Property | Type | Description | | :: | :: | :: | | `serverTime` | integer | The current time of the server in Unix Milliseconds. | +| `whoami` | integer \| null | The userID you are authenticated as. If you are not authenticated, this is null. | | `version` | string | The current version of Tachi-Server running. | | `permissions` | Array<string> | The permissions this request had. | | `echo` (Conditional) | string | If an `echo` parameter was provided, this is that exact parameter. | From d161f7a8d8c424cc681ac1eaab17ad83fc58803d Mon Sep 17 00:00:00 2001 From: zkldi Date: Mon, 28 Jun 2021 17:05:35 +0100 Subject: [PATCH 11/12] remove params --- docs/docs/api/routes/games.md | 78 +++++++++++++++++++++++++++++ docs/docs/api/routes/gpt.md | 31 ++++++++++++ docs/docs/api/routes/user-gamept.md | 68 ++++++++++++------------- docs/docs/api/routes/users.md | 4 +- docs/mkdocs.yml | 3 ++ 5 files changed, 148 insertions(+), 36 deletions(-) create mode 100644 docs/docs/api/routes/games.md create mode 100644 docs/docs/api/routes/gpt.md 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" From b2adbb0bb251eb1e2291d97da80652b47a994f46 Mon Sep 17 00:00:00 2001 From: zkldi Date: Mon, 28 Jun 2021 17:38:50 +0100 Subject: [PATCH 12/12] Add GPT documentation --- docs/docs/api/routes/gpt.md | 318 +++++++++++++++++++++++++++++++++++- 1 file changed, 315 insertions(+), 3 deletions(-) diff --git a/docs/docs/api/routes/gpt.md b/docs/docs/api/routes/gpt.md index 0dccd793d..4d0e55a63 100644 --- a/docs/docs/api/routes/gpt.md +++ b/docs/docs/api/routes/gpt.md @@ -12,20 +12,332 @@ programmatically, you should see [Game Endpoints](./games.md). ### Parameters +None. + ### Response | Property | Type | Description | | :: | :: | :: | +| `config` | GamePTConfig | The configuration file for this game + playtype. | +!!! warning + A GamePTConfig is different to a GameConfig! Read more + [here](../../codebase/implementation-details/game-configuration.md). ### Example #### Request ``` - +GET /api/v1/games/iidx/SP ``` - - #### Response +```json +{ + "config": { + "idString": "iidx:SP", + + "percentMax": 100, + + "defaultScoreRatingAlg": "ktRating", + "defaultSessionRatingAlg": "ktRating", + "defaultProfileRatingAlg": "ktRating", + + // ... more props - a lot more props + } +} +``` + +***** + +## Retrieve the player leaderboard. + +`GET /api/v1/leaderboard` + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `alg` (Optional) | String | If present, specifies an alternative algorithm to sort players on, instead of the default. | +| `start` (Optional) | Integer | If present, specifies a starting point to display the leaderboard from. Essentially pagination. | + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `gameStats` | GameStats[] | The sorted statistics for the leaderboards. | +| `users` | UserDocument[] | All of the related users for the above statistics. | + +### Example + +#### Request +``` +GET /api/v1/games/iidx/SP/leaderboard +``` + +#### Response + +```json +{ + "gameStats": [{ + "userID": 1, + "ratings": { + "ktRating": 4, + // ... + } + // ... + }], + "users": [{ + "id": 1, + "username": "zkldi" + }] +} +``` + +***** + +## Retrieve a song and its charts. + +`GET /api/v1/games/:game/:playtype/songs/:songID` + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `song` | SongDocument | The requested song document. | +| `charts` | ChartDocument[] | All of the charts that belong to this song for this playtype. | + +### Example + +#### Request +``` +GET /api/v1/games/iidx/SP/songs/1 +``` + +#### Response + +```json +{ + "song": { + "id": 1, + "title": "5.1.1." + }, + "charts": [{ + "songID": 1, + "playtype": "SP", + "difficulty": "HYPER", + // ... + }, { + "songID": 1, + "playtype": "SP", + "difficulty": "ANOTHER", + // ... + }] +} +``` + +***** + +## Get popular charts for this game + playtype. + +`GET /api/v1/games/:game/:playtype/charts` + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `search` (Optional) | String | A song title to search for. | + +!!! note + If no search parameter is set, then the most popular + 100 charts for this game are returned. + + If a search parameter is set, then the most popular + charts that match the search criteria will be returned, + in that order. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `charts` | Array<ChartDocument with `__playcount`> | The chart documents that matched this search, or the most popular 100 charts for this game. | +| `songs` | Array<SongDocument> | The associated song documents for the charts. | + +!!! info + The `__playcount` property is patched onto the chart + documents returned. This indicates the amount of unique + players that have played this chart. + +### Example + +#### Request +``` +GET /api/v1/games/iidx/SP/charts?search=AA +``` + +#### Response + +```json +{ + "songs": [{ + "title": "AA", + "id": 3, + // ... + }, { + "title": "AA -rebuild-", + "id": 133, + // ... + }], + "charts": [{ + "songID": 3, + "difficulty": "ANOTHER", + "__playcount": 1049, + // ... + }, { + "songID": 133, + "difficulty": "ANOTHER", + "__playcount": 120 + }, + //... + ] +} +``` + +***** + +## Retrieve a chart at a specific ID. + +`GET /api/v1/games/:game/:playtype/charts/:chartID` + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `song` | SongDocument | The parent song for this chart. | +| `chart` | ChartDocument | The requested chart document. | + +### Example + +#### Request +``` +GET /api/v1/games/iidx/SP/charts/some_chart_id +``` + +#### Response + +```json +{ + "song": { + "id": 123, + "title": "BLOCKS", + // ... + }, + "chart": { + "chartID": "some_chart_id", + "songID": 123, + "playtype": "SP", + // ... + } +} +``` + +***** + +## Retrieve playcount for this chart. + +`GET /api/v1/games/:game/:playtype/charts/:chartID/playcount` + +### Parameters + +None. + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `count` | Integer | The amount of plays on this chart. | + +### Example + +Self-explanatory. + +***** + +## Retrieve leaderboards for this chart. + +`GET /api/v1/games/:game/:playtype/charts/:chartID/pbs` + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `startRanking` (Optional) | Specify a start point to return 100 pbs from. Defaults to 1. Inclusive. | + +### Response + +| Property | Type | Description | +| :: | :: | :: | +| `pbs` | Array<PBDocument> | The array of pbs sorted by ranking. | +| `users` | The users these PBs belong to. | + +### Example + +#### Request +``` +GET /api/v1/games/iidx/SP/charts/some_chart/pbs +``` + +#### Response + +```json +{ + "pbs": [{ + "chartID": "some_chart", + "userID": 1, + "rankingData": { + "rank": 1, + "outOf": 100, + }, + // ... + }, + //... + ], + "users": [{ + "id": 1, + "username": "zkldi", + // ... + }, + // ... + ] +} +``` + +***** + +## Search for a user's PB on this chart. + +`GET /api/v1/games/:game/:playtype/charts/:chartID/pbs/search` + +### Parameters + +| Property | Type | Description | +| :: | :: | :: | +| `search` | String | The user whose PB you're searching for. | + +### Response + +Same as `/api/v1/games/:game/:playtype/charts/:chartID/pbs`. + +### Example + +See Above. +