mirror of
https://github.com/zkldi/Tachi.git
synced 2026-10-13 01:38:29 +03:00
Massive Documentation Improvements
This commit is contained in:
zkldi
@@ -23,8 +23,8 @@ Where API_KEY is the api key you wish to use.
|
||||
|
||||
The other way to authorise a request is with your session cookie. This **MUST NOT** be used by code, and is instead a way for logged-in users to interact with the API as themselves.
|
||||
|
||||
To use authentication in this way, simply make a request with your `ktchi_production_session` or
|
||||
`btchi_production_session` cookie.
|
||||
To use authentication in this way, simply make a request with your `Kamaitachi_SESSION` or
|
||||
`Bokutachi_SESSION` cookie.
|
||||
|
||||
The reason for this second authentication method is so that, when a user logs in, they can use
|
||||
the cookie they were set to also interact with the API.
|
||||
|
||||
@@ -68,7 +68,7 @@ As the name implies, the Success Response is returned on a successful request.
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `success` | true | Always true for a successful response. |
|
||||
| `description` | string | Information about what happened with the request. |
|
||||
| `description` | String | Information about what happened with the request. |
|
||||
| `body` | Endpoint Dependent | Any data that the endpoint needs to return, such as a user's document from a profile request. |
|
||||
|
||||
The HTTP Status Code for any Success Response will always be of 2XX form.
|
||||
@@ -80,10 +80,14 @@ As the name implies, the Failed Response is returned when a request fails.
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `success` | false | Always false for a failed response. |
|
||||
| `description` | string | Information about what went wrong with the request. |
|
||||
| `description` | String | Information about what went wrong with the request. |
|
||||
|
||||
The HTTP Status Code for any Failed Response will always be of either 4XX or 5XX form.
|
||||
|
||||
!!! warning
|
||||
The `description` property is **NOT** intended for program usage. You should **NEVER** depend
|
||||
on the output of `description`, as it may be changed at any time for any reason.
|
||||
|
||||
!!! note
|
||||
Any API request can fail for any reason. You should always account for the
|
||||
case where the request fails.
|
||||
|
||||
+174
-27
@@ -1,6 +1,7 @@
|
||||
# Admin Endpoints
|
||||
|
||||
These endpoints are for adminstrator use.
|
||||
These endpoints are for adminstrator use. As such, they all
|
||||
require an `authLevel` of atleast 3. For more information, see the [UserDocument](/tachi-server/documents/user).
|
||||
|
||||
*****
|
||||
|
||||
@@ -42,32 +43,6 @@ Empty Object.
|
||||
|
||||
*****
|
||||
|
||||
## Remove the isPrimary status from a chart
|
||||
|
||||
This also uncalcs all score data for scores on the chart.
|
||||
|
||||
`POST /api/v1/admin/deprimarify`
|
||||
|
||||
### Permissions
|
||||
|
||||
- Admin
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `chartID` | String | The chartID to deprimarify. |
|
||||
| `game` | Game | The game this chart is on. |
|
||||
| `songID` | Integer | Alternatively to chartID, you can specify this to deprimarify all charts on this songID. |
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `charts` | Array<ChartDocument> | The array of charts that were deprimarified |
|
||||
|
||||
*****
|
||||
|
||||
## Delete any Score
|
||||
|
||||
This performs all the necessary checks to remove a score document aswell.
|
||||
@@ -88,3 +63,175 @@ This performs all the necessary checks to remove a score document aswell.
|
||||
|
||||
Empty Object.
|
||||
|
||||
*****
|
||||
|
||||
## Resynchronise all PBs that match the given query or users.
|
||||
|
||||
`POST /api/v1/admin/resync-pbs`
|
||||
|
||||
!!! info
|
||||
This is intended to be used in the case that PBs fall out of
|
||||
sync with what they should be. This could be due to a
|
||||
database migration going awry, or anything else.
|
||||
|
||||
### Permissions
|
||||
|
||||
- Admin
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `userIDs` | Array<Integer> (Optional) | The list of userIDs to resynchronise PBs for. |
|
||||
| `filters` | Mongo Query for the PBs Collection. (Optional) | A query to reduce the amount of PBs that get reprocessed. |
|
||||
|
||||
### Response
|
||||
|
||||
Empty Object.
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
POST /api/v1/admin/resync-pbs
|
||||
```
|
||||
|
||||
```js
|
||||
{
|
||||
"filter": {
|
||||
"game": {$in: ["iidx","sdvx"]}
|
||||
},
|
||||
"userIDs": [1,2,3,4]
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
Nothing.
|
||||
|
||||
*****
|
||||
|
||||
## Destroy a users GPT Profile and forces a leaderboard recalc.
|
||||
|
||||
`POST /api/v1/admin/destroy-ugpt`
|
||||
|
||||
!!! warning
|
||||
This is intended to completely remove a users GPT profile.
|
||||
You should use this **only** if a user has irrevocably screwed
|
||||
their account. Preferably early on!
|
||||
|
||||
### Permissions
|
||||
|
||||
- Admin
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `userID` | Integer | The user part of the UGPT. |
|
||||
| `game` | Game | The game part of the UGPT. |
|
||||
| `playtype` | Playtype | The PT part of the UGPT. Must be for the above game. |
|
||||
|
||||
### Response
|
||||
|
||||
Empty Object.
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
POST /api/v1/admin/destroy-ugpt
|
||||
```
|
||||
|
||||
```js
|
||||
{
|
||||
"userID": 1,
|
||||
"game": "iidx",
|
||||
"playtype": "DP"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
Empty Object.
|
||||
|
||||
*****
|
||||
|
||||
## Destroy a chart and all of its scores.
|
||||
|
||||
`POST /api/v1/admin/destroy-chart`
|
||||
|
||||
### Permissions
|
||||
|
||||
- Admin
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `chartID` | String | The chartID you wish to destroy. |
|
||||
| `game` | Game | The game this chart belongs to (Necessary for lookups). |
|
||||
|
||||
### Response
|
||||
|
||||
Empty Object.
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
POST /api/v1/admin/destroy-chart
|
||||
```
|
||||
```js
|
||||
{
|
||||
"chartID": "SomeChartID",
|
||||
"game": "iidx"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
Empty Object.
|
||||
|
||||
*****
|
||||
|
||||
## Perform a site recalc on this set of scores.
|
||||
|
||||
`POST /api/v1/admin/recalc`
|
||||
|
||||
### Permissions
|
||||
|
||||
- Admin
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | Mongo Query for scores | Filters the amount of scores recalced. If not provided, defaults to every score on the site. |
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `scoresRecalced` | Integer | The amount of scores recalced. |
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
POST /api/v1/admin/recalc
|
||||
```
|
||||
```js
|
||||
{
|
||||
"game": "iidx",
|
||||
"scoreData.percent": {$gt: 90},
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```js
|
||||
{
|
||||
"scoresRecalced": 174
|
||||
}
|
||||
```
|
||||
|
||||
+158
-16
@@ -9,7 +9,11 @@ These endpoints relate to internal authentication methods. Read the warning belo
|
||||
Furthermore, interacting with this programmatically
|
||||
is near-impossible because you need to complete a CAPTCHA.
|
||||
|
||||
This is documented for completeness' sake.
|
||||
Nevertheless, This is documented for completeness' sake.
|
||||
|
||||
!!! warning
|
||||
All of these endpoints are aggressively rate limited. If you fire a bot at this, you will probably get
|
||||
your IP blacklisted. Don't do that.
|
||||
|
||||
*****
|
||||
|
||||
@@ -23,15 +27,21 @@ Logs a user in and returns a session cookie.
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `username` | string | The user's username. This is compared case-insensitively.
|
||||
| `password` | string | The user's password. |
|
||||
| `captcha` | string | |
|
||||
| `username` | String | The user's username. This is compared case-insensitively.
|
||||
| `!password` | String | The user's password. |
|
||||
| `captcha` | String | Information about the captcha filled out by the user. We use a Google ReCaptcha instance. |
|
||||
|
||||
!!! info
|
||||
The `!` prefix is special in that anything with it is assumed to be private and is **always**
|
||||
ignored by our request logger.
|
||||
|
||||
Without it, we would log passwords!
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `userID` | integer | The ID of the user you authenticated as. |
|
||||
| `userID` | Integer | The ID of the user you authenticated as. |
|
||||
|
||||
| HTTP Header | Description |
|
||||
| :: | :: |
|
||||
@@ -48,7 +58,7 @@ POST /api/v1/auth/login
|
||||
```json
|
||||
{
|
||||
"username": "zkldi",
|
||||
"password": "my_password",
|
||||
"!password": "my_password",
|
||||
"captcha": "herebedragons"
|
||||
}
|
||||
```
|
||||
@@ -70,19 +80,18 @@ POST /api/v1/auth/login
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `username` | string | A string between 3 and 20 characters. The first character must be A-Z, _ or -. The other 19 may be A-Z, 0-9, _ or -. |
|
||||
| `password` | string | An 8 character or longer string. |
|
||||
| `email` | string | |
|
||||
| `inviteCode` (Kamaitachi Only) | string | If on Kamaitachi, this is the user's invitation code. |
|
||||
| `captcha` | string | |
|
||||
| `username` | String | A string between 3 and 20 characters. The first character must be A-Z, _ or -. The other 19 may be A-Z, 0-9, _ or -. |
|
||||
| `!password` | String | An 8 character or longer string. |
|
||||
| `email` | String | |
|
||||
| `inviteCode` (Kamaitachi Only) | String (Undefined/Unused on Bokutachi) | If on Kamaitachi, this is the user's invitation code. |
|
||||
| `captcha` | String | |
|
||||
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `id` | integer | The newly-created user's ID. |
|
||||
| `username` | string | The newly-created user's name. |
|
||||
| `<body>` | [UserDocument](/tachi-server/documents/user)| The newly-created user's User Document. |
|
||||
|
||||
### Example
|
||||
|
||||
@@ -93,8 +102,8 @@ POST /api/v1/auth/register
|
||||
|
||||
```json
|
||||
{
|
||||
"username": "newguy",
|
||||
"password": "my_password",
|
||||
"username": "newGuy",
|
||||
"!password": "my_password",
|
||||
"captcha": "herebedragons",
|
||||
"email": "test@example.com"
|
||||
}
|
||||
@@ -105,10 +114,78 @@ POST /api/v1/auth/register
|
||||
```json
|
||||
{
|
||||
"id": 2,
|
||||
"username": "newguy"
|
||||
"username": "newGuy",
|
||||
"usernameLowercase": "newguy",
|
||||
"socialMedia": {
|
||||
"discord": null,
|
||||
"twitter": null,
|
||||
"github": null,
|
||||
"steam": null,
|
||||
"youtube": null,
|
||||
"twitch": null
|
||||
},
|
||||
"joinDate": 1639628634978,
|
||||
"lastSeen": 1639628634978,
|
||||
"about": "I'm a fairly nondescript person.",
|
||||
"status": null,
|
||||
"customPfpLocation": null,
|
||||
"customBannerLocation": null,
|
||||
"clan": null,
|
||||
"badges": [],
|
||||
"authLevel": 1
|
||||
}
|
||||
```
|
||||
|
||||
*****
|
||||
|
||||
## Verify an email from the code that was sent to it.
|
||||
|
||||
`POST /api/v1/auth/verify-email`
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `code` | String | The Code that was sent to the users mailbox. |
|
||||
|
||||
### Response
|
||||
|
||||
Empty Object
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
{
|
||||
"code": "abcdef1234567890"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
Empty Object.
|
||||
|
||||
*****
|
||||
|
||||
## Resend a verification email to the requesting user's email address.
|
||||
|
||||
`POST /api/v1/auth/resend-verify-email`
|
||||
|
||||
**Requires Self-Key Level Auth**
|
||||
|
||||
### Parameters
|
||||
|
||||
None, This endpoint reads the requesting user from their session.
|
||||
|
||||
### Response
|
||||
|
||||
Empty object.
|
||||
|
||||
### Example
|
||||
|
||||
N/A
|
||||
|
||||
|
||||
*****
|
||||
|
||||
## Log Out.
|
||||
@@ -135,3 +212,68 @@ POST /api/v1/auth/logout
|
||||
#### Response
|
||||
|
||||
Nothing.
|
||||
|
||||
*****
|
||||
|
||||
## Create a password reset code and send it to the provided email.
|
||||
|
||||
`POST /api/v1/auth/forgot-password`
|
||||
|
||||
!!! note
|
||||
This endpoint sends the password reset code pretty-printed to the email, and is **NOT**
|
||||
returned as part of the HTTP request.
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `email` | String | A user's email. If the email does not correspond to any accounts, 202 is returned anyway as a security measure. |
|
||||
|
||||
### Response
|
||||
|
||||
Empty Object. The endpoint immediately returns 202 to avoid giving away information about registered emails.
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```js
|
||||
{
|
||||
"email": "zkldi.dev@gmail.com"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
Although the request body returns nothing, `zkldi.dev@gmail.com` will have recieved an email with
|
||||
a URL containing the password reset code.
|
||||
|
||||
*****
|
||||
|
||||
## Reset a user's password with a password reset code.
|
||||
|
||||
`POST /api/v1/auth/reset-password`
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `code` | String | A password reset code. This is provided in a password reset email. |
|
||||
| `!password` | String | The password to change to. |
|
||||
|
||||
### Response
|
||||
|
||||
Empty Object.
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```js
|
||||
{
|
||||
"code": "1234567890abcdef",
|
||||
"!password": "zkldi_is_so_cool",
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
Empty Object.
|
||||
|
||||
@@ -6,7 +6,7 @@ For a detailed explaination on how to use the OAuth2 flow, you can check [Using
|
||||
|
||||
*****
|
||||
|
||||
!!! warn
|
||||
!!! warning
|
||||
All endpoints on this list require [Self Key](./user-integrations.md) level authentication.
|
||||
|
||||
That is to say, it cannot be performed using Bearer tokens, and must be done by the user themselves.
|
||||
@@ -198,7 +198,7 @@ PATCH /api/v1/clients/some_client_id
|
||||
|
||||
`POST /api/v1/clients/:clientID/reset-secret`
|
||||
|
||||
!!! warn
|
||||
!!! warning
|
||||
This does **NOT** reset api keys created by this client as per OAuth2 spec.
|
||||
|
||||
If you need that functionality, you will need to delete
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
# Config Endpoints
|
||||
|
||||
These endpoints display certain properties about the Tachi [config file](../../tachi-server/setup/config.md).
|
||||
|
||||
*****
|
||||
|
||||
## Return the value of the BEATORAJA_QUEUE_SIZE
|
||||
|
||||
`GET /api/v1/config/beatoraja-queue-size`
|
||||
|
||||
**Bokutachi Only**
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | Integer | The value in `conf.json5` for BEATORAJA_QUEUE_SIZE. |
|
||||
|
||||
|
||||
## Return the value of the USC_QUEUE_SIZE
|
||||
|
||||
`GET /api/v1/config/usc-queue-size`
|
||||
|
||||
**Bokutachi Only**
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | Integer | The value in `conf.json5` for USC_QUEUE_SIZE. |
|
||||
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Example Endpoint
|
||||
|
||||
*Endpoints will be formatted like this.*
|
||||
*Endpoints will be formatted like this. - These are not real endpoints!*
|
||||
|
||||
*****
|
||||
|
||||
@@ -27,8 +27,8 @@ This endpoint greets the user.
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `name` | string | The name of the user to greet. |
|
||||
| `birthday` (optional) | presence | Whether it is the user's birthday or not. |
|
||||
| `name` | String | The name of the user to greet. |
|
||||
| `birthday` (optional) | Presence | Whether it is the user's birthday or not. |
|
||||
|
||||
Not providing required parameters will result in a 400 error.
|
||||
|
||||
@@ -55,8 +55,8 @@ Not providing required parameters will result in a 400 error.
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `greeting` | string | A greeting for the user. |
|
||||
| `wasBirthday` | boolean | Whether today is the users birthday or not. |
|
||||
| `greeting` | String | A greeting for the user. |
|
||||
| `wasBirthday` | Boolean | Whether today is the users birthday or not. |
|
||||
|
||||
!!! info
|
||||
Since the above table corresponds to keys in the `body`
|
||||
@@ -67,7 +67,7 @@ Not providing required parameters will result in a 400 error.
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | string | The greeting. |
|
||||
| `<body>` | String | The greeting. |
|
||||
|
||||
Corresponds to:
|
||||
```json
|
||||
@@ -110,4 +110,5 @@ GET /greet?name=zkldi
|
||||
}
|
||||
```
|
||||
|
||||
This is omitted, because it's redundant all of the time.
|
||||
This is omitted, because it's redundant all of the time. -- That is to say,
|
||||
You should never depend on parsing the content of `description`.
|
||||
@@ -65,8 +65,8 @@ GET /api/v1/games/iidx/SP
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `gameStats` | GameStats[] | The sorted statistics for the leaderboards. |
|
||||
| `users` | UserDocument[] | All of the related users for the above statistics. |
|
||||
| `gameStats` | Array<GameStats> | The sorted statistics for the leaderboards. |
|
||||
| `users` | Array<[UserDocument](/tachi-server/documents/user)gt; | All of the related users for the above statistics. |
|
||||
|
||||
### Example
|
||||
|
||||
@@ -258,7 +258,7 @@ GET /api/v1/games/iidx/SP/charts/some_chart_id
|
||||
Retrieve the tierlist information for this chart. If no tierlistID is provided, this falls back
|
||||
to the GPT's default.
|
||||
|
||||
!!! warn
|
||||
!!! warning
|
||||
If the GPT has no default tierlist, then the server will return a 501.
|
||||
|
||||
### Parameters
|
||||
@@ -589,10 +589,10 @@ GET /api/v1/games/bms/7K/tableID/insane
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `pbs` | Array<PBScoreDocument> | The array of pbs part of the score leaderboard. |
|
||||
| `pbs` | Array<PBDocument> | The array of pbs part of the score leaderboard. |
|
||||
| `songs` | Array<SongDocument> | The array of songs part of the PBs. |
|
||||
| `charts` | Array<ChartDocument> | The array of charts part of the PBs. |
|
||||
| `users` | Array<UserDocument> | The array of users part of the PBs. |
|
||||
| `users` | Array<[UserDocument](/tachi-server/documents/user)gt; | The array of users part of the PBs. |
|
||||
|
||||
*****
|
||||
|
||||
@@ -655,7 +655,7 @@ GET /api/v1/games/bms/7K/player-distribution?class=stslDan
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `users` | Array<UserDocument> | Array of the users who achieved the courses. |
|
||||
| `users` | Array<[UserDocument](/tachi-server/documents/user)gt; | Array of the users who achieved the courses. |
|
||||
| `classes` | Array<ClassAchievementDocument> | Data about the recently achieved classes. |
|
||||
|
||||
*****
|
||||
@@ -674,7 +674,7 @@ GET /api/v1/games/bms/7K/player-distribution?class=stslDan
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `scores` | Array<ScoreDocument> | The highlighted scores. |
|
||||
| `users` | Array<UserDocument> | The users who own the scores. |
|
||||
| `scores` | Array<[ScoreDocument](/tachi-server/documents/score)> | The highlighted scores. |
|
||||
| `users` | Array<[UserDocument](/tachi-server/documents/user)gt; | The users who own the scores. |
|
||||
| `songs` | Array<SongDocument> | The songs the scores are on. |
|
||||
| `charts` | Array<ChartDocument> | The charts the scores are on. |
|
||||
|
||||
@@ -6,8 +6,6 @@
|
||||
|
||||
```POST /api/v1/import/file```
|
||||
|
||||
**Kamaitachi Only**.
|
||||
|
||||
Perform a score import that depends on a file, such as a .csv import.
|
||||
|
||||
### Permissions
|
||||
@@ -22,8 +20,8 @@ appropriate way to send files.
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `importType` | string | The ImportType this import is for. This only accepts `file/` ImportTypes. |
|
||||
| `scoreData` | file | The file to import scores from. |
|
||||
| `importType` | String | The ImportType this import is for. This only accepts `file/` [ImportTypes](../../tachi-server/import/import-types.md). |
|
||||
| `scoreData` | File | The file to import scores from. |
|
||||
|
||||
| HTTP Header | Description |
|
||||
| :: | :: |
|
||||
@@ -32,13 +30,29 @@ appropriate way to send files.
|
||||
!!! info
|
||||
It's the responsibility of the API user to use the X-User-Intent
|
||||
header properly. It should only be used when the user
|
||||
has explicitly requested this import (i.e. not an automated script).
|
||||
has explicitly requested this import (i.e. not sent by an automated script).
|
||||
|
||||
### Response
|
||||
|
||||
**Implementation Dependent**.
|
||||
There are two reponse scenarios for this endpoint, depending on whether the server uses an external score processor or not.
|
||||
|
||||
#### External Score Processor Response
|
||||
|
||||
If an external score processor is being used, **202** is returned as a status code, and you are given the following:
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | ImportDocument | The Import Document created as a result of this import. |
|
||||
| `url` | String | A URL to poll for information about this import, while it's being processed. |
|
||||
| `importID` | String | The ID of the import currently being processed. |
|
||||
|
||||
#### Internal Score Processor Response
|
||||
|
||||
If score processing is not done externally, the following is returned:
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | ImportDocument | The import document created as a result of this import. |
|
||||
|
||||
### Example
|
||||
|
||||
@@ -84,6 +98,15 @@ scoreData=<file data>
|
||||
}
|
||||
```
|
||||
|
||||
**OR**
|
||||
|
||||
```js
|
||||
{
|
||||
url: "https://bokutachi.xyz/api/v1/imports/SOME_IMPORT_ID/poll-status",
|
||||
importID: "SOME_IMPORT_ID"
|
||||
}
|
||||
```
|
||||
|
||||
*****
|
||||
|
||||
## Synchronise scores up with an API.
|
||||
@@ -108,9 +131,25 @@ be performed programmatically, as long as the key has `submit_score` permissions
|
||||
|
||||
### Response
|
||||
|
||||
**Implementation Dependent**.
|
||||
There are two reponse scenarios for this endpoint, depending on whether the server uses an external score processor or not.
|
||||
|
||||
#### External Score Processor Response
|
||||
|
||||
If an external score processor is being used, **202** is returned as a status code, and you are given the following:
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | ImportDocument | Information about this import. |
|
||||
| `url` | String | A URL to poll for information about this import, while it's being processed. |
|
||||
| `importID` | String | The ID of the import currently being processed. |
|
||||
|
||||
#### Internal Score Processor Response
|
||||
|
||||
If score processing is not done externally, the following is returned:
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | ImportDocument | The import document created as a result of this import. |
|
||||
|
||||
### Example
|
||||
|
||||
@@ -126,4 +165,51 @@ POST /api/v1/import/from-api
|
||||
|
||||
#### Response
|
||||
|
||||
See previous big example.
|
||||
See previous example.
|
||||
|
||||
*****
|
||||
|
||||
## Force Tachi to reprocess your orphanned scores.
|
||||
|
||||
`POST /api/v1/import/orphans`
|
||||
|
||||
|
||||
This endpoint goes through all of the requesting user's [Orphanned Scores](../../tachi-server/import/orphans.md) and attempts to find them a parent song & chart.
|
||||
|
||||
!!! note
|
||||
Scores automatically attempt de-orphaning every day on Kamaitachi and Bokutachi,
|
||||
this endpoint just allows you to force a deorphaning, should you wish to.
|
||||
|
||||
### Permissions
|
||||
|
||||
- submit_score
|
||||
|
||||
### Parameters
|
||||
|
||||
None.
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `processed` | Integer | The amount of orphans processed. |
|
||||
| `failed` | Integer | The amount of orphans that did not find a parent chart, and were kept as orphans. |
|
||||
| `success` | Integer | The amount of orphans that successfully found a parent chart, and were turned into real scores. |
|
||||
| `removed` | Integer | The amount of orphans removed -- They found a parent chart, but were rejected by the converter for being invalid scores, such as having unsupported options or impossible score values. |
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
|
||||
N/A
|
||||
|
||||
#### Response
|
||||
|
||||
```js
|
||||
{
|
||||
"processed": 100,
|
||||
"failed": 95,
|
||||
"success": 2,
|
||||
"removed": 3
|
||||
}
|
||||
```
|
||||
|
||||
@@ -81,7 +81,7 @@ None.
|
||||
| `userID` | Integer | The user this code belongs to. |
|
||||
| `createdOn` | Number | The time in unix milliseconds that this code was created. |
|
||||
|
||||
!!! warn
|
||||
!!! warning
|
||||
These codes expire around 30 minutes from their creation.
|
||||
|
||||
### Example
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `search` | string | What to search for. |
|
||||
| `search` | String | What to search for. |
|
||||
|
||||
### Response
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ None.
|
||||
| `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. |
|
||||
| `user` | [UserDocument](/tachi-server/documents/user)| The user that made this session. |
|
||||
|
||||
### Example
|
||||
|
||||
|
||||
@@ -16,18 +16,19 @@ It's a good way of sanity checking whether your code works.
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `echo` | string | A string to echo. This is useful for checking whether parameters are sending over properly. |
|
||||
| `echo` | String | A string to echo. This is useful for checking whether parameters are sending over properly. |
|
||||
|
||||
|
||||
### Response
|
||||
|
||||
| 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. |
|
||||
| `serverTime` | Integer | The current time of the server in Unix Milliseconds. |
|
||||
| `startTime` | Integer | The time this server was booted 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. |
|
||||
| `echo` (Conditional) | String | If an `echo` parameter was provided, this is that exact parameter. |
|
||||
|
||||
### Example
|
||||
|
||||
@@ -57,8 +58,9 @@ bodies properly.
|
||||
### Example
|
||||
|
||||
```json
|
||||
POST /status
|
||||
---
|
||||
POST /api/v1/status
|
||||
```
|
||||
```
|
||||
{
|
||||
"echo": "hello world"
|
||||
}
|
||||
|
||||
@@ -21,7 +21,7 @@ None.
|
||||
| `gameStats` | UserGameStatsDocument | The User's GameStats for this game + playtype. |
|
||||
| `firstScore` | ScoreDocument or Null | The user's first score for this game + playtype. This is null if the user has no scores with timestamps. |
|
||||
| `mostRecentScore` | ScoreDocument or Null | The user's most recent score. This is null if the user has no scores with timestamps. |
|
||||
| `totalScores` | integer | The total amount of scores this user has. |
|
||||
| `totalScores` | Integer | The total amount of scores this user has. |
|
||||
| `rankingData` | Record<Rating Algorithm, { ranking: integer, outOf: integer }> | The position of this player on the default leaderboards for this game, and how many players it is out of. |
|
||||
|
||||
### Example
|
||||
@@ -297,6 +297,59 @@ GET /api/v1/users/zkldi/games/iidx/SP/pbs/best?alg=BPI
|
||||
|
||||
*****
|
||||
|
||||
## Returns all of a users personal bests.
|
||||
|
||||
`GET /api/v1/users/:userID/games/:game/:playtype/pbs/all`
|
||||
|
||||
### Parameters
|
||||
|
||||
None.
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `pbs` | Array<PBDocument> | All of the users PB Documents |
|
||||
| `songs` | Array<SongDocument> | All of the relevant songs. |
|
||||
| `charts` | Array<ChartDocument> | All of the relevant charts. |
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
GET /api/v1/users/zkldi/games/iidx/SP/pbs/all
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```js
|
||||
{
|
||||
pbs: [{
|
||||
userID: 1,
|
||||
scoreData: {
|
||||
score: 123,
|
||||
// ...
|
||||
}
|
||||
}],
|
||||
songs: [{
|
||||
title: "Verflucht",
|
||||
// ...
|
||||
}],
|
||||
charts: [{
|
||||
songID: 123,
|
||||
playtype: "SP",
|
||||
difficulty: "ANOTHER",
|
||||
// ...
|
||||
}, {
|
||||
songID: 123,
|
||||
playtype: "SP",
|
||||
difficulty: "HYPER",
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
*****
|
||||
|
||||
## Get A User's PB for a given chart.
|
||||
|
||||
`GET /api/v1/users/:userID/games/:game/:playtype/pbs/:chartID`
|
||||
@@ -467,7 +520,7 @@ song titles of played songs inside sessions.
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `search` | string | The session name to search for. |
|
||||
| `search` | String | The session name to search for. |
|
||||
|
||||
### Response
|
||||
|
||||
@@ -510,7 +563,7 @@ These are returned in descending order.
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `alg` (Optional) | string | The name of the algorithm to use instead of the default. |
|
||||
| `alg` (Optional) | String | The name of the algorithm to use instead of the default. |
|
||||
|
||||
### Response
|
||||
|
||||
@@ -572,6 +625,44 @@ None.
|
||||
| :: | :: | :: |
|
||||
| `<body>` | Array<SessionDocument> | The array of the users sessions. |
|
||||
|
||||
*****
|
||||
|
||||
## Get a user's most recent session.
|
||||
|
||||
`GET /api/v1/users/:userID/games/:game/:playtype/sessions/last`
|
||||
|
||||
!!! info
|
||||
This endpoint will return 404 if the user has never had a
|
||||
session for this game.
|
||||
|
||||
### Parameters
|
||||
|
||||
None.
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | SessionDocument | The user's most recent session. |
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
GET /api/v1/users/zkldi/games/iidx/SP/sessions/last
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```js
|
||||
{
|
||||
"name": "foo",
|
||||
"desc": "My most recent session",
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## Get a user's most recent 100 highlighted sessions.
|
||||
|
||||
`GET /api/v1/users/:userID/games/:game/:playtype/sessions/highlighted`
|
||||
@@ -609,7 +700,8 @@ GET /api/v1/users/zkldi/games/iidx/SP/sessions/highlighted
|
||||
ktRating: 14,
|
||||
bpi: 3
|
||||
}
|
||||
highlight: true
|
||||
highlight: true,
|
||||
// ... more props
|
||||
},
|
||||
]
|
||||
```
|
||||
@@ -698,7 +790,7 @@ GET /api/v1/users/zkldi/games/iidx/SP/most-played
|
||||
| :: | :: | :: |
|
||||
| `above` | Array<UserGameStats> | Up to 5 users' game stats better than this user. |
|
||||
| `below` | Array<UserGameStats> | Same as above, but below the user. |
|
||||
| `users` | Array<UserDocument> | The user documents related to the above statistics. |
|
||||
| `users` | Array<[UserDocument](/tachi-server/documents/user)gt; | The user documents related to the above statistics. |
|
||||
| `thisUsersStats` | UserGameStats | The requested user's stats for this GPT. |
|
||||
| `thisUsersRanking` | {outOf: integer, ranking: integer} | The requested user's ranking for this GPT. |
|
||||
|
||||
@@ -810,7 +902,7 @@ GET /api/v1/users/1/games/iidx/SP/history
|
||||
|
||||
`GET /api/v1/users/:userID/games/:game/:playtype/settings`
|
||||
|
||||
!!! warn
|
||||
!!! warning
|
||||
Unlike most other applications, your settings are completely public. GPT Settings only concern
|
||||
cosmetic things, like what rating algorithms to prefer.
|
||||
|
||||
|
||||
@@ -46,6 +46,8 @@ GET /api/v1/users/1/integrations/kai/flo
|
||||
|
||||
`POST /api/v1/users/:userID/integrations/kai/:kaiType/oauth2callback`
|
||||
|
||||
**Kamaitachi Only**
|
||||
|
||||
!!! info
|
||||
This is used as part of an [OAuth2 Flow](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2).
|
||||
|
||||
@@ -60,7 +62,7 @@ GET /api/v1/users/1/integrations/kai/flo
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `code` | string | The intermediate code to use to get the access_token and refresh_token. |
|
||||
| `code` | String | The intermediate code to use to get the access_token and refresh_token. |
|
||||
|
||||
### Response
|
||||
|
||||
@@ -174,7 +176,7 @@ PATCH /api/v1/users/1/integrations/arc
|
||||
}
|
||||
```
|
||||
|
||||
!!! warn
|
||||
!!! warning
|
||||
This endpoint doesn't do any checking on the `accountID` parameter to check whether it actually
|
||||
works with ARC. There is also no checking to see whether you're the owner of this account.
|
||||
|
||||
|
||||
@@ -19,7 +19,10 @@ These endpoints are related to users in general.
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | Array<UserDocument> | The array of up to 100 users returned. |
|
||||
| `<body>` | Array<[UserDocument](/tachi-server/documents/user)gt; | The array of up to 100 users returned. |
|
||||
|
||||
!!! note
|
||||
Users are guaranteeably returned in order of when they were `lastSeen`.
|
||||
|
||||
### Example
|
||||
|
||||
@@ -45,28 +48,25 @@ GET /api/v1/users
|
||||
|
||||
`GET /api/v1/users/:userID`
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
|
||||
|
||||
!!! 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 username - zkldi (This is also case-insensitive, so you could pass ZkLDi).
|
||||
You may also pass the special string - `me` - which
|
||||
will select whatever user this authentication token
|
||||
is for.
|
||||
will select whatever user you are authenticated as.
|
||||
|
||||
### Parameters
|
||||
|
||||
None.
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | UserDocument | The user this ID/username corresponds to. |
|
||||
| `<body>` | [UserDocument](/tachi-server/documents/user)| The user this ID/username corresponds to. |
|
||||
|
||||
### Example
|
||||
|
||||
@@ -82,7 +82,9 @@ GET /api/v1/users/zkldi
|
||||
OR
|
||||
GET /api/v1/users/1
|
||||
OR
|
||||
GET /api/v1/users/me WHEN authenticated as userID 1.
|
||||
GET /api/v1/users/zkLDI (It's case insensitive!)
|
||||
OR
|
||||
GET /api/v1/users/me IF authenticated as userID 1.
|
||||
```
|
||||
|
||||
#### Response
|
||||
@@ -97,6 +99,61 @@ GET /api/v1/users/me WHEN authenticated as userID 1.
|
||||
|
||||
*****
|
||||
|
||||
## Modify this user document.
|
||||
|
||||
`PATCH /api/v1/users/:userID`
|
||||
|
||||
### Permissions
|
||||
|
||||
- Self-Key level authentication as this user.
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `about` | String | An about me. This is rendered as markdown. |
|
||||
| `status` | String \| Null | The users status. If null, this will be unset. |
|
||||
| `discord`, `twitter`, `github`, `steam`, `youtube`, `twitch` | String \| Null | Information about this users social media. If null, this field will be unset. |
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `<body>` | [UserDocument](/tachi-server/documents/user)| The user document with all of those changes applied. |
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```js
|
||||
{
|
||||
"about": "#Hello!**I'm zkldi**",
|
||||
"status": "I'm cool!",
|
||||
"twitter": null,
|
||||
"steam": "zkldi"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```js
|
||||
{
|
||||
"id": 1,
|
||||
"username": "zkldi",
|
||||
"usernameLowercase": "zkldi",
|
||||
"socialMedia": {
|
||||
"twitter": null,
|
||||
"steam": "zkldi",
|
||||
// this property was already here, and not modified by the request.
|
||||
"discord": "zkldi#2965",
|
||||
},
|
||||
"about": "#Hello!**I'm zkldi**",
|
||||
"status": "I'm cool!",
|
||||
// and other user props...
|
||||
}
|
||||
```
|
||||
|
||||
*****
|
||||
|
||||
## Retrieve user's statistics on all games.
|
||||
|
||||
`GET /api/v1/users/:userID/game-stats`
|
||||
@@ -228,7 +285,7 @@ None.
|
||||
|
||||
### Response
|
||||
|
||||
Not JSON. This returns the actual JPG or PNG stored for
|
||||
**Not JSON**. This returns the actual JPG or PNG stored for
|
||||
this user.
|
||||
|
||||
### Example
|
||||
@@ -237,14 +294,12 @@ N/A
|
||||
|
||||
*****
|
||||
|
||||
*****
|
||||
|
||||
## Unset your profile picture.
|
||||
|
||||
`DELETE /api/v1/users/:userID/pfp`
|
||||
|
||||
!!! note
|
||||
If you do not have a profile picture set, this is
|
||||
If you do not have a profile picture set, this will be
|
||||
a 404 error.
|
||||
|
||||
### Permissions
|
||||
|
||||
Reference in New Issue
Block a user