mirror of
https://github.com/zkldi/Tachi.git
synced 2026-10-02 11:58:12 +03:00
Merge pull request #16 from zkldi/develop
Add User Integrations API Documentation
This commit is contained in:
zkldi
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2021 zkldi
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
@@ -600,4 +600,148 @@ GET /api/v1/users/zkldi/games/iidx/SP/sessions/highlighted
|
||||
highlight: true
|
||||
},
|
||||
]
|
||||
```
|
||||
|
||||
*****
|
||||
|
||||
## Get a user's most played charts.
|
||||
|
||||
`GET /api/v1/users/:userID/games/:game/:playtype/most-played`
|
||||
|
||||
### Parameters
|
||||
|
||||
None.
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `songs` | Array<SongDocument> | The array of songs related to the pbs. |
|
||||
| `charts` | Array<ChartDocument> | The array of charts related to the pbs. |
|
||||
| `pbs` | Array<(PBDocument & {__playcount: integer})> | An array of PB documents with the `__playcount` property attached. This property dictates how many times the user has played this chart. |
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
GET /api/v1/users/zkldi/games/iidx/SP/most-played
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```js
|
||||
{
|
||||
songs: [{
|
||||
id: 1,
|
||||
title: "5.1.1.",
|
||||
// ...
|
||||
}, {
|
||||
id: 2,
|
||||
title: "GAMBOL",
|
||||
// ...
|
||||
}],
|
||||
charts: [{
|
||||
songID: 1,
|
||||
difficulty: "ANOTHER",
|
||||
// ...
|
||||
}, {
|
||||
songID: 2,
|
||||
difficulty: "LEGGENDARIA",
|
||||
// ...
|
||||
}, {
|
||||
songID: 1,
|
||||
difficulty: "HYPER",
|
||||
}],
|
||||
pbs: [{
|
||||
chartID: "something",
|
||||
__playcount: 5,
|
||||
// ...
|
||||
}, {
|
||||
chartID: "something_else",
|
||||
__playcount: 2,
|
||||
// ...
|
||||
}, {
|
||||
chartID: "something_more",
|
||||
__playcount: 1,
|
||||
// ...
|
||||
}]
|
||||
}
|
||||
```
|
||||
|
||||
*****
|
||||
|
||||
## Retrieve a leaderboard around a user.
|
||||
|
||||
`GET /api/v1/users/:userID/games/:game/:playtype/leaderboard-adjacent`
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `alg` | String (Optional) | Optionally, you can provide an override algorithm to use for the leaderboards instead of the game+playtype default. |
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `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. |
|
||||
| `thisUsersStats` | UserGameStats | The requested user's stats for this GPT. |
|
||||
| `thisUsersRanking` | {outOf: integer, ranking: integer} | The requested user's ranking for this GPT. |
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
GET /api/v1/users/zkldi/games/iidx/SP/leaderboard-adjacent
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```js
|
||||
{
|
||||
above: [{
|
||||
userID: 2,
|
||||
ratings: {
|
||||
ktRating: 9
|
||||
},
|
||||
classes: {
|
||||
dan: 10
|
||||
},
|
||||
// ...
|
||||
}],
|
||||
below: [{
|
||||
userID: 3,
|
||||
ratings: {
|
||||
ktRating: 1
|
||||
},
|
||||
classes: {
|
||||
dan: 5
|
||||
},
|
||||
// ...
|
||||
}],
|
||||
users: [{
|
||||
userID: 2,
|
||||
username: "sptmgtm",
|
||||
// ...
|
||||
}, {
|
||||
userID: 3,
|
||||
username: "neil.c",
|
||||
// ...
|
||||
}],
|
||||
thisUsersStats: {
|
||||
userID: 1,
|
||||
ratings: {
|
||||
ktRating: 5
|
||||
},
|
||||
classes: {
|
||||
dan: 5
|
||||
}
|
||||
},
|
||||
thisUsersRanking: {
|
||||
ranking: 2,
|
||||
outOf: 3
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,182 @@
|
||||
# User Integrations
|
||||
|
||||
These endpoints are related to a users integrations with external services.
|
||||
|
||||
*****
|
||||
|
||||
## Retrieve whether this user is authenticated with this kaiType.
|
||||
|
||||
`GET /api/v1/users/:userID/integrations/kai/:kaiType`
|
||||
|
||||
**Kamaitachi Only**
|
||||
|
||||
!!! note
|
||||
A KaiType is either "flo", "min", or "eag". Since these three services
|
||||
share backends, they all use the same authentication mechanisms, and share
|
||||
endpoints like this.
|
||||
|
||||
### Permissions
|
||||
|
||||
- Self-key: This request must be made using Cookie authentication, which means it cannot be used with API keys.
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `authStatus` | boolean | True if the user is authenticated with this kaiType, false if they are not. |
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
GET /api/v1/users/1/integrations/kai/flo
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```js
|
||||
{
|
||||
authStatus: false
|
||||
}
|
||||
```
|
||||
|
||||
*****
|
||||
|
||||
## Update a user's access_token and refresh_token from an intermediate code.
|
||||
|
||||
`POST /api/v1/users/:userID/integrations/kai/:kaiType/oauth2callback`
|
||||
|
||||
!!! info
|
||||
This is used as part of an [OAuth2 Flow](https://www.digitalocean.com/community/tutorials/an-introduction-to-oauth-2).
|
||||
|
||||
The client controls the callback link after authentication with the service, and then POSTs the returned `code` to us.
|
||||
This part of the flow actually updates the user.
|
||||
|
||||
### Permissions
|
||||
|
||||
- Self-key
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `code` | string | The intermediate code to use to get the access_token and refresh_token. |
|
||||
|
||||
### Response
|
||||
|
||||
Empty object for body. 200 on success, not 200 on failure - status code depending on error.
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```js
|
||||
{
|
||||
code: "This_Is_An_1nT3rMeDIate_Code"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```js
|
||||
{}
|
||||
```
|
||||
|
||||
*****
|
||||
|
||||
## Retrieve a users ARC integrations.
|
||||
|
||||
`GET /api/v1/users/:userID/integrations/arc`
|
||||
|
||||
**Kamaitachi Only**
|
||||
|
||||
### Permissions
|
||||
|
||||
- Self-Key
|
||||
|
||||
### Parameters
|
||||
|
||||
None.
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `iidx` | ArcAuthDoc \| null | Whether this user is authenticated for `api/arc-iidx` or not. |
|
||||
| `sdvx` | See above | See above, but for `api/arc-sdvx`. |
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```
|
||||
GET /api/v1/users/1/integrations/arc
|
||||
```
|
||||
|
||||
#### Response
|
||||
|
||||
```js
|
||||
{
|
||||
iidx: {
|
||||
userID: 1,
|
||||
accountID: "arc_account_id_here",
|
||||
forImportType: "api/arc-iidx"
|
||||
},
|
||||
sdvx: null
|
||||
}
|
||||
```
|
||||
|
||||
*****
|
||||
|
||||
## Update ARC Integrations
|
||||
|
||||
`PATCH /api/v1/users/:userID/integrations/arc`
|
||||
|
||||
### Permissions
|
||||
|
||||
- Self-Key
|
||||
|
||||
### Parameters
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `iidx` | Optional, String or Null | Change your configured AccountID for ARC IIDX. If not present, change nothing. If null, remove link, if string, update accountID. |
|
||||
| `sdvx` | Optional, String or Null | See above, but for SDVX |
|
||||
|
||||
|
||||
### Response
|
||||
|
||||
| Property | Type | Description |
|
||||
| :: | :: | :: |
|
||||
| `iidx` | ArcAuthDoc \| null | This user's current ArcAuthDoc (or null) for IIDX. |
|
||||
| `sdvx` | ArcAuthDoc \| null | This user's current ArcAuthDoc (or null) for SDVX. |
|
||||
|
||||
### Example
|
||||
|
||||
#### Request
|
||||
```js
|
||||
PATCH /api/v1/users/1/integrations/arc
|
||||
|
||||
---
|
||||
{
|
||||
iidx: "newAccountID",
|
||||
sdvx: null, // remove this account ID.
|
||||
}
|
||||
```
|
||||
|
||||
#### Response
|
||||
```js
|
||||
{
|
||||
iidx: {
|
||||
forImportType: "api/arc-iidx",
|
||||
accountID: "newAccountID",
|
||||
userID: 1
|
||||
},
|
||||
sdvx: null
|
||||
}
|
||||
```
|
||||
|
||||
!!! warn
|
||||
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.
|
||||
|
||||
Of course, this means you could trivially cheat by pointing your account at someone elses.
|
||||
This would be a violation of R2, and result in an account ban.
|
||||
@@ -6,7 +6,7 @@ These endpoints are related to users in general.
|
||||
|
||||
## List Users
|
||||
|
||||
` /api/v1/users`
|
||||
`/api/v1/users`
|
||||
|
||||
### Parameters
|
||||
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
# Notable Terminology
|
||||
|
||||
Similar to the userland terminology document - Tachi has some internal terminology that you should
|
||||
be familiar with.
|
||||
|
||||
## GPT
|
||||
|
||||
Refers to "Game + Playtype" - a combination of a game and its playtype.
|
||||
|
||||
## UGPT
|
||||
|
||||
Refers to "User on Game + Playtype" - A user's "something" on a game and that playtype.
|
||||
@@ -4,7 +4,7 @@ To ensure that the score tracker stays accurate,
|
||||
and everyone has a nice time, Tachi enforces some
|
||||
rules.
|
||||
|
||||
## Be civil.
|
||||
## R1: Be civil.
|
||||
|
||||
In various places in Tachi you may write things, such
|
||||
as comments on your scores, or a profile about me.
|
||||
@@ -20,7 +20,7 @@ The punishment for this ranges from warnings to permanent bans, depending on the
|
||||
|
||||
Generally, just be a nice person. Please!
|
||||
|
||||
## You **MUST NOT** deliberately fake score submissions to Tachi.
|
||||
## R2: You **MUST NOT** deliberately fake score submissions to Tachi.
|
||||
|
||||
The punishment for this is an instant, permanent
|
||||
IP ban.
|
||||
@@ -43,7 +43,7 @@ may be warned.
|
||||
You do not get a second chance. If you fake scores, you
|
||||
revoke all access to the tracker.
|
||||
|
||||
## You **MUST NOT** play on invalid input devices.
|
||||
## R3: You **MUST NOT** play on invalid input devices.
|
||||
|
||||
Games on Tachi have specific requirements for what kind of
|
||||
setups are 'legitimate'. That means that you **SHOULD NOT**
|
||||
@@ -78,7 +78,7 @@ The valid input devices are listed below.
|
||||
| BMS (14K) | any two IIDX Controllers | Keyboard play is **NOT** allowed for BMS 14K. |
|
||||
|
||||
|
||||
## Do not harm other people in the community.
|
||||
## R4: Do not harm other people in the community.
|
||||
|
||||
This rule is depressing to write, but it has to be said.
|
||||
|
||||
@@ -114,13 +114,13 @@ which includes, **but is not limited to**:
|
||||
stupid.)
|
||||
- Not liking another community member.
|
||||
|
||||
## You are only allowed one account.
|
||||
## R5: You are only allowed one account.
|
||||
|
||||
Do not make multiple accounts, we track account IPs and it
|
||||
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.
|
||||
## R6: Do not set NSFW artwork as your avatar or banner.
|
||||
|
||||
Tachi does not allow you to set suggestive or NSFW
|
||||
artwork as your avatar or banner. Your avatar will be
|
||||
@@ -132,7 +132,7 @@ deleted and you will be warned.
|
||||
Uploading illegal (under international common or EU law)
|
||||
material will result in an immediate permanent ban.
|
||||
|
||||
## Use Common Sense.
|
||||
## R7: Use Common Sense.
|
||||
|
||||
This list of rules isn't exhaustive, and staff reserve the
|
||||
right to ban you at any time for any reason. You should use
|
||||
|
||||
@@ -43,6 +43,7 @@ nav:
|
||||
- API Reference:
|
||||
- "api/overview.md"
|
||||
- "api/auth.md"
|
||||
- "api/terminology.md"
|
||||
|
||||
- Endpoints:
|
||||
- "api/routes/example.md"
|
||||
@@ -51,6 +52,7 @@ nav:
|
||||
- "api/routes/auth.md"
|
||||
- "api/routes/users.md"
|
||||
- "api/routes/user-gamept.md"
|
||||
- "api/routes/user-integrations.md"
|
||||
- "api/routes/sessions.md"
|
||||
- "api/routes/scores.md"
|
||||
- "api/routes/search.md"
|
||||
|
||||
Reference in New Issue
Block a user