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..4d0e55a63 --- /dev/null +++ b/docs/docs/api/routes/gpt.md @@ -0,0 +1,343 @@ +# 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 + +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. + 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 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/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. | diff --git a/docs/docs/api/routes/user-gamept.md b/docs/docs/api/routes/user-gamept.md index ad7cfd356..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 @@ -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 | +| :: | :: | :: | + + + + +| `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` @@ -309,9 +356,9 @@ 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. | + + + | `search` | String | Limits the returned scores to those where the corresponding song is most similar to this query. | ### Response @@ -374,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 @@ -435,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 @@ -481,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 @@ -526,4 +573,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 | +| :: | :: | :: | + + + + +### 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 diff --git a/docs/docs/api/routes/users.md b/docs/docs/api/routes/users.md index 6aa2c0fd8..8dbbeabb1 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 }] @@ -49,7 +49,18 @@ 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, + 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 @@ -70,13 +81,15 @@ 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 ```js { - userID: 1, + id: 1, username: "zkldi", // ... so on } @@ -92,7 +105,7 @@ GET /api/v1/users/1 | Property | Type | Description | | :: | :: | :: | -| `:userID` | URL Parameter | The user ID or username to fetch the data of. | + ### Response @@ -138,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. 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/docs/codebase/setup/config.md b/docs/docs/codebase/setup/config.md index be39c55db..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) @@ -134,21 +149,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. - 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. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index fd5ccbba8..cd6bf2b6b 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,11 @@ nav: - "api/routes/auth.md" - "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"