blob: 487b2d364035d280eebaa9627c407072505b9c35 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
|
# 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)
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 | | |
## 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 |
## How to test API endpoints
```sh
# If you're running the standalone flask server:
curl http://localhost:5000/<endpoint>
# If you're running flask and nginx at the same time:
curl http://localhost:2080/api/<endpoint>
```
## 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:
```py
# api/tests/example.py
from flask import Blueprint
example = Blueprint('example', __name__)
@example.route('/example')
def index():
# python dictionaries are automatically converted to JSON by flask
return {"hello": "world"}, 200 # flask returns http code 200 by default if no code is explicitly defined
# define a `dynamic_route` variable at the end of your endpoint definition file
# dynamic_route[0] is the namespace
# dynamic_route[1] is your flask.Blueprint
dynamic_route = ["/tests", status]
# this endpoint will be routed to /tests/example
# \___/ \_____/
# | |
# | endpoint (defined by the @Blueprint.route() decorator)
# |
# namespace (defined in dynamic_route variable)
```
|