diff options
author | lonkaars <l.leblansch@gmail.com> | 2021-04-05 18:53:19 +0200 |
---|---|---|
committer | lonkaars <l.leblansch@gmail.com> | 2021-04-05 18:53:19 +0200 |
commit | 0da8098559b7134c090d8ed58d61d145a9310211 (patch) | |
tree | 414c7891d168957c97f70a148997bf170c9faa95 /api/readme.md | |
parent | cfdc08e9d0ced27541e51c8f7cc7544e1ba8225c (diff) |
partial api docs move :tada:
Diffstat (limited to 'api/readme.md')
-rw-r--r-- | api/readme.md | 487 |
1 files changed, 447 insertions, 40 deletions
diff --git a/api/readme.md b/api/readme.md index 26ef02b..70aeaf5 100644 --- a/api/readme.md +++ b/api/readme.md @@ -6,51 +6,458 @@ This is the subdirectory for the API. You can find the API reference in [this](h API return type classes are mostly defined in api/api.ts -endpoint|method|description|parameters|authorization --|-|-|-|- -/status | GET | get online user count and active game count -/auth/login | POST | log in with email or username -/auth/token | POST | log in using a token (stored as cookie) -/auth/signup | POST | sign up -/user/info | GET\|POST | get user info by username or id note: avatar is a uri to a 256x256 .png image -/user/games | GET\|POST | get games of user -/user/avatar | GET\|POST | fetch or update avatar note: avatar is a client-resized 256x256 .png base64-encoded image, request returns error when image is not .png or larger than 256x256 -/user/prefrences | GET\|POST | fetch or change user preferences -/user/password | POST | update password -/user/email | POST | update email (token used for authentication if password is undefined) -/user/username | POST | update username (token used for authentication if password is undefined) -/user/status | POST | update status -/user/searchFriends | POST | search user's friend list -/social/request | POST | send a friend request to a user by user id -/social/accept | POST | accept a friend request -/social/remove | POST | remove a friend from your friend list or delete a friend request from a user -/social/search | POST | search for users by username or status -/social/block | POST | block a user -/social/unblock | POST | unblock a user -/social/list/requests | GET | get a list of unaccepted friend requests -/social/list/blocks | GET | get a list of blocked people -/social/list/friends | GET | get a list of your friends -/game/new | POST | create a new private game -/game/random | POST | join or create a public game -/game/info | POST | -/game/accept | POST | accept game invite or rematch -/game/spectate | POST | spectate a game by id +<table> +<code> +<thead> +<tr> +<th>endpoint</th> +<th>method</th> +<th>description</th> +<th>parameters</th> +<th>authorization</th> +<th>response</th> +</tr> +</thead> +<tbody> + +<tr> +<td>/status</td> +<td><code><code>GET</code></code></td> +<td>get online user count and active game count</td> +<td><code>none</code></td> +<td><code>none</code></td> +<td> + +```ts +{ + users: int, + games: int +} +``` +</td> +</tr> + +<tr> +<td>/auth/login</td> +<td><code>POST</code></td> +<td>log in with email or username</td> +<td> + +```ts +{ + email: string, + password: string +} +``` +</td> +<td><code>none</code></td> +<td>empty response with the set_cookie header</td> +</tr> + +<tr> +<td>/auth/signup</td> +<td><code>POST</code></td> +<td>sign up</td> +<td> + +```ts +{ + username: string, + email: string, + password: string +} +``` +</td> +<td><code>none</code></td> +<td>empty response with the set_cookie header</td> +</tr> + +<tr> +<td>/user/info</td> +<td><code>GET|POST</code></td> +<td>get user info by username or id note: avatar is a uri to a 256x256 .png image</td> +<td> + +```ts +{ + username?: string, + id?: userID +} +``` +</td> +<td><code>none|user</code></td> +<td> + +```ts +userInfo +``` +</td> +</tr> + +<tr> +<td>/user/games</td> +<td><code>GET|POST</code></td> +<td>get games of user</td> +<td> + +```ts +{ id?: userID } +``` +</td> +<td><code>none|user</code></td> +<td> + +```ts +{ + games: Array<gameInfo>, + totals: userGameTotals +} +``` +</td> +</tr> + +<tr> +<td>/user/avatar</td> +<td><code>GET</code></td> +<td>fetch avatar as .png</td> +<td> + +```ts +{ id?: userID } +``` +</td> +<td><code>none|user</code></td> +<td>PNG image</td> +</tr> + +<tr> +<td>/user/avatar</td> +<td><code>POST</code></td> +<td> +update avatar + +note: avatar is a client-resized 256x256 .png base64-encoded image, request +returns error when image is not .png or larger than 256x256 +</td> +<td> + +```ts +{ image: base64PNG } +``` +</td> +<td><code>user</code></td> +<td><code>none</code></td> +</tr> + +<tr> +<td>/user/prefrences</td> +<td><code>GET</code></td> +<td>fetch user preferences</td> +<td><code>none</code></td> +<td><code>user</code></td> +<td> + +```ts +{ preferences: userPreferences } +``` +</td> +</tr> + +<tr> +<td>/user/prefrences</td> +<td><code>POST</code></td> +<td>change user preferences</td> +<td> + +```ts +{ newPreferences: userPreferences } +``` +</td> +<td><code>user</code></td> +<td><code>none</code></td> +</tr> + +<tr> +<td>/user/password</td> +<td>POST</td> +<td>update password</td> +<td> + +```ts +{ + password: string, + newPassword: string, +} +``` +</td> +<td><code>user</code></td> +<td><code>none</code></td> +</tr> + +<tr> +<td>/user/email</td> +<td>POST</td> +<td>update email</td> +<td> + +```ts +{ + password: string, + email: string, +} +``` +</td> +<td><code>user</code></td> +<td><code>none</code></td> +</tr> + +<tr> +<td>/user/username</td> +<td>POST</td> +<td>update username</td> +<td> + +```ts +{ + password: string, + username: string, +} +``` +</td> +<td><code>user</code></td> +<td><code>none</code></td> +</tr> + +<tr> +<td>/user/status</td> +<td><code>POST</code></td> +<td>update status</td> +<td> + +```ts +{ status: string } +``` +</td> +<td><code>user</code></td> +<td><code>none</code></td> +</tr> + +<tr> +<td>/user/searchFriends</td> +<td><code>POST</code></td> +<td>search user's friend list</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/social/request</td> +<td><code>POST</code></td> +<td>send a friend request to a user by user id</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/social/accept</td> +<td><code>POST</code></td> +<td>accept a friend request</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/social/remove</td> +<td><code>POST</code></td> +<td>remove a friend from your friend list or delete a friend request from a user</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/social/search</td> +<td><code>POST</code></td> +<td>search for users by username or status</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/social/block</td> +<td><code>POST</code></td> +<td>block a user</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/social/unblock</td> +<td><code>POST</code></td> +<td>unblock a user</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/social/list/requests</td> +<td><code>GET</code></td> +<td>get a list of unaccepted friend requests</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/social/list/blocks</td> +<td><code>GET</code></td> +<td>get a list of blocked people</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/social/list/friends</td> +<td><code>GET</code></td> +<td>get a list of your friends</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/game/new</td> +<td><code>POST</code></td> +<td>create a new private game</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/game/random</td> +<td><code>POST</code></td> +<td>join or create a public game</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/game/info</td> +<td><code>POST</code></td> +<td></td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/game/accept</td> +<td><code>POST</code></td> +<td>accept game invite or rematch</td> +<td></td> +<td></td> +</tr> + +<tr> +<td>/game/spectate</td> +<td><code>POST</code></td> +<td>spectate a game by id</td> +<td></td> +<td></td> +</tr> + +</tbody> +</code> +</table> ## Events These are events that are fired by the socket.io connection -event|description|data|direction|context --|-|-|-|- -fieldUpdate|recieve new playfield from server|`{ field: string }`|`s -> c`|game -turnUpdate|recieve if it's player 1's move|`{ player1: boolean }`|`s -> c`|game -gameStart|sent when game starts|`none`|`s -> c`|game -finish|sent when game finishes|`none`|`s -> c`|game -resign|send to resign, is then forwarded to all subscribed clients|`none`|`s <-> c`|game -newMove|send a new move|`{ move: int, game_id: string }`|`s <- c`|game -registerGameListener|listen to events for a game|`{ id: string }`|`s <- c`|game -incomingFriendRequest|get notified of friend request|`none`|`s -> c`|global -changedRelation|get notified of a different relation to someone|`{ id: string }`|`s -> c`|global +<table> +<thead> + +<tr> +<th>event</th> +<th>description</th> +<th>data</th> +<th>direction</th> +<th>context</th> +</tr> + +</thead> +<tbody> + +<tr> +<td>fieldUpdate</td> +<td>recieve new playfield from server</td> +<td><code>{ field: string }</code></td> +<td><code>s -> c</code></td> +<td>game</td> +</tr> + +<tr> +<td>turnUpdate</td> +<td>recieve if it's player 1's move</td> +<td><code>{ player1: boolean }</code></td> +<td><code>s -> c</code></td> +<td>game</td> +</tr> + +<tr> +<td>gameStart</td> +<td>sent when game starts</td> +<td><code>none</code></td> +<td><code>s -> c</code></td> +<td>game</td> +</tr> + +<tr> +<td>finish</td> +<td>sent when game finishes</td> +<td><code>none</code></td> +<td><code>s -> c</code></td> +<td>game</td> +</tr> + +<tr> +<td>resign</td> +<td>send to resign, is then forwarded to all subscribed clients</td> +<td><code>none</code></td> +<td><code>s <-> c</code></td> +<td>game</td> +</tr> + +<tr> +<td>newMove</td> +<td>send a new move</td> +<td><code>{ move: int, game_id: string }</code></td> +<td><code>s <- c</code></td> +<td>game</td> +</tr> + +<tr> +<td>registerGameListener</td> +<td>listen to events for a game</td> +<td><code>{ id: string }</code></td> +<td><code>s <- c</code></td> +<td>game</td> +</tr> + +<tr> +<td>incomingFriendRequest</td> +<td>get notified of friend request</td> +<td><code>none</code></td> +<td><code>s -> c</code></td> +<td>global</td> +</tr> + +<tr> +<td>changedRelation</td> +<td>get notified of a different relation to someone</td> +<td><code>{ id: string }</code></td> +<td><code>s -> c</code></td> +<td>global</td> +</tr> + +</tbody> +</table> ## How to test API endpoints ```sh |