From b9e1d1537bb9b8b178d9d6cb7aca06d8cfc068a4 Mon Sep 17 00:00:00 2001 From: lonkaars Date: Fri, 16 Apr 2021 16:36:58 +0200 Subject: complete api documentation in api/readme.md --- api/game/accept.py | 2 +- api/readme.md | 335 +++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 246 insertions(+), 91 deletions(-) (limited to 'api') diff --git a/api/game/accept.py b/api/game/accept.py index bf63c46..1f73fd1 100644 --- a/api/game/accept.py +++ b/api/game/accept.py @@ -14,7 +14,7 @@ join_game = Blueprint('game_accept', __name__) # join a game by game_id (public or private) @join_game.route('/accept', methods=['POST']) -@auth_required("user") +@auth_required("user") #FIXME: this doesn't work haha i don't know when i wrote this def index(game_id): if cursor.execute("select status from games where game_id = ?", [game_id]).fetchone()[0] != "wait_for_opponent": diff --git a/api/readme.md b/api/readme.md index fbaeba1..f46c812 100644 --- a/api/readme.md +++ b/api/readme.md @@ -1,10 +1,6 @@ # 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. - -## Endpoint reference (WIP) +## Endpoint reference API return type classes are mostly defined in api/api.ts @@ -15,7 +11,7 @@ API return type classes are mostly defined in api/api.ts method description parameters -authorization +minimal authorization response @@ -78,20 +74,35 @@ API return type classes are mostly defined in api/api.ts /user/info -GET|POST -get user info by username or id note: avatar is a uri to a 256x256 .png image +POST +get user info by id ```ts -{ id?: userID } +{ id: userID } ``` -none|user +none + + +```ts +{ userInfo } +``` + + + + + +/user/info +GET + +none +user ```ts -userInfo; +{ userInfo } ``` @@ -99,16 +110,16 @@ userInfo; /user/games -GET|POST +POST get games of user ```ts -{ id?: userID } +{ id: userID } ``` -none|user +none ```ts @@ -122,17 +133,38 @@ userInfo; -/user/avatar +/user/games GET -fetch avatar as .png + +none +user ```ts -{ id?: userID } +{ + games: Array, + totals: userGameTotals +} ``` -none|user + + + +/user/avatar?id= +GET +fetch avatar as .png using url parameter +none +none +PNG image + + + +/user/avatar +GET +fetch avatar as .png +none +user PNG image @@ -149,10 +181,7 @@ returns error when image is not .png or larger than 256x256 ```ts -{ - image: - base64PNG; -} +{ image: base64PNG; } ``` @@ -169,10 +198,7 @@ returns error when image is not .png or larger than 256x256 ```ts -{ - preferences: - userPreferences; -} +{ preferences: userPreferences; } ``` @@ -185,10 +211,7 @@ returns error when image is not .png or larger than 256x256 ```ts -{ - newPreferences: - userPreferences; -} +{ newPreferences: userPreferences; } ``` @@ -198,7 +221,7 @@ returns error when image is not .png or larger than 256x256 /user/password -POST +POST update password @@ -216,7 +239,7 @@ returns error when image is not .png or larger than 256x256 /user/email -POST +POST update email @@ -234,7 +257,7 @@ returns error when image is not .png or larger than 256x256 /user/username -POST +POST update username @@ -257,10 +280,7 @@ returns error when image is not .png or larger than 256x256 ```ts -{ - status: - string; -} +{ status: string; } ``` @@ -268,124 +288,254 @@ returns error when image is not .png or larger than 256x256 none - -/user/searchFriends -POST -search user's friend list - - - - /social/request POST send a friend request to a user by user id - - + + +```ts +{ id: userID } +``` + + +user +none /social/accept POST accept a friend request - - + + +```ts +{ id: userID } +``` + + +user +none /social/remove POST remove a friend from your friend list or delete a friend request from a user - - + + +```ts +{ id: userID } +``` + + +user +none /social/search POST search for users by username or status - - + + +```ts +{ query: string } +``` + + +none + + +```ts +{ results: Array } +``` + + /social/block POST block a user - - + + +```ts +{ id: userID } +``` + + +user +none /social/unblock POST unblock a user - - + + +```ts +{ id: userID } +``` + + +user +none /social/list/requests GET get a list of unaccepted friend requests - - +none +user + + +```ts +{ requests: Array } +``` + + /social/list/blocks GET get a list of blocked people - - +none +user + + +```ts +{ blocks: Array } +``` + + /social/list/friends GET get a list of your friends - - +none +user + + +```ts +{ friends: Array } +``` + + /game/new POST create a new private game - - +none +user + + +```ts +{ + id: gameID, + player_1: boolean, + game_started: boolean, +} +``` + + /game/random POST join or create a public game - - +none +user + + +```ts +{ + id: gameID, + player_1: boolean, + game_started: boolean, +} +``` + + /game/info POST - - - +get game info by game id + + +```ts +{ id: gameID } +``` + + +user + + +```ts +{ gameInfo } +``` + + /game/accept POST accept game invite or rematch - - + + +```ts +{ id: gameID } +``` + + +user + + +```ts +{ + id: gameID, + player_1: boolean, + game_started: boolean, +} +``` + + /game/spectate POST spectate a game by id - - + + +```ts +{ id: gameID } +``` + + +none + + +```ts +{ + id: gameID, + player_1: boolean, + game_started: boolean, +} +``` + + @@ -495,24 +645,9 @@ curl http://localhost:5000/ curl http://localhost:2080/api/ ``` -## How to add new API endpoints - -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 - ## Example endpoint -Here's a simple endpoint that returns an empty JSON object: +Here's a simple endpoint that returns a "hello world" JSON object: ```py # api/tests/example.py @@ -537,3 +672,23 @@ dynamic_route = ["/tests", status] # | # namespace (defined in dynamic_route variable) ``` + +## Handy utility functions and where to find them + +All of the paths are defined relative to this (api/) directory. Most of these +functions/decorators should also have docstrings for editor autocompletion +help, but not all of them do. + +utility | description | file +-----------------------------------|--------------------------------------------------------------------------|------------- +`@util_two_id(type)` | exposes (token_id, explicit_id) to the endpoint | hierarchy.py +`@two_person` | exposes (user_1_id, user_2_id) to the endpoint | hierarchy.py +`@one_person` | exposes (user_id) to the endpoint | hierarchy.py +`@game_id_with_viewer` | exposes (game_id, viewer?) to the endpoint | hierarchy.py +`@auth_required(level)` | checks if user is authorized and expose (user_id) to the endpoint | hierarchy.py +`@io_auth_required(level)` | same as @auth_required but for socket.io event listeners | hierarchy.py +`all_def([ ... ])` | checks if all items of the list are truthy | util.py +`all_notdef([ ... ])` | checks if all items of the list are falsy | util.py +`format_user(user_id, viewer_id?)` | format a user to /api/user/info format with optional viewer for relation | user/info.py +`format_game(game_id, viewer_id?)` | format a game to /api/game/info format with optional viewer for opponent | game/info.py + -- cgit v1.2.3