diff options
Diffstat (limited to 'posts/po4-api.md')
| -rw-r--r-- | posts/po4-api.md | 105 |
1 files changed, 51 insertions, 54 deletions
diff --git a/posts/po4-api.md b/posts/po4-api.md index 487b2d3..0ca148b 100644 --- a/posts/po4-api.md +++ b/posts/po4-api.md @@ -1,61 +1,63 @@ +[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> @@ -68,16 +70,10 @@ 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 @@ -106,3 +102,4 @@ dynamic_route = ["/tests", status] # | # namespace (defined in dynamic_route variable) ``` + |