aboutsummaryrefslogtreecommitdiff
path: root/posts/po4-api.md
diff options
context:
space:
mode:
authorlonkaars <l.leblansch@gmail.com>2021-04-12 10:25:43 +0200
committerlonkaars <l.leblansch@gmail.com>2021-04-12 10:25:43 +0200
commit822d1ee1be99b7d96740585ddd1174b94916335d (patch)
tree7005e359d7f62dede5f3eabe02becec37d8bfe57 /posts/po4-api.md
parent7f7e14bd9dce02e6ced663fd527a5750cd13f920 (diff)
dprint formatter :tada:
Diffstat (limited to 'posts/po4-api.md')
-rw-r--r--posts/po4-api.md105
1 files changed, 54 insertions, 51 deletions
diff --git a/posts/po4-api.md b/posts/po4-api.md
index 0ca148b..487b2d3 100644
--- a/posts/po4-api.md
+++ b/posts/po4-api.md
@@ -1,63 +1,61 @@
-[meta]: <title> (po connect-4 api readme)
-[meta]: <tags> (po4, po-connect-4, api, rest)
-[meta]: <date> (April 1 2021)
-[meta]: <author> (Loekaars)
-
# API
-This is the subdirectory for the API. You can find the API reference in [this](https://docs.google.com/spreadsheets/d/1mDN9IUqRIMjr_9RmLxKybjIgVuaUadalmPEFnG-XeJg/edit?usp=sharing) Google Docs document.
+This is the subdirectory for the API. You can find the API reference in
+[this](https://docs.google.com/spreadsheets/d/1mDN9IUqRIMjr_9RmLxKybjIgVuaUadalmPEFnG-XeJg/edit?usp=sharing)
+Google Docs document.
## Endpoint reference (WIP)
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
+| 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 | | |
## 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
+| 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 |
## How to test API endpoints
+
```sh
# If you're running the standalone flask server:
curl http://localhost:5000/<endpoint>
@@ -70,10 +68,16 @@ curl http://localhost:2080/api/<endpoint>
Please follow these rules when creating new API endpoints:
-1. Endpoints should always return a valid JSON object and an appropriate [http code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
-2. Endpoints that are in a namespace should get their own directory in this folder, eg. http://localhost:5000/status is defined in api/status.py, http://localhost:5000/auth/signup is defined in api/auth/signup.py etc.
-3. Endpoints that take data should verify that the data is present and valid, and return an empty JSON object with http code 400 (bad request) if the data isn't valid.
-4. Endpoints that require database access should get the cursor/connection object from api/db.py
+1. Endpoints should always return a valid JSON object and an appropriate
+ [http code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes)
+2. Endpoints that are in a namespace should get their own directory in this
+ folder, eg. http://localhost:5000/status is defined in api/status.py,
+ http://localhost:5000/auth/signup is defined in api/auth/signup.py etc.
+3. Endpoints that take data should verify that the data is present and valid,
+ and return an empty JSON object with http code 400 (bad request) if the data
+ isn't valid.
+4. Endpoints that require database access should get the cursor/connection
+ object from api/db.py
## Example endpoint
@@ -102,4 +106,3 @@ dynamic_route = ["/tests", status]
# |
# namespace (defined in dynamic_route variable)
```
-