search

UCLA-Creative-Labs / aurgy-backend

the logic behind generating out-of-body music playlists
MIT License
3 stars 0 forks source link

👀 Tracking: available functional apis for aurgy backend #33

Open BryanPan342 opened 2 years ago

BryanPan342 commented 2 years ago

Below is a list of available APIs and their status:

Icon Status
✅ Implemented and go to go as documented
❌ Not implemented
🚧 In progress

Express Endpoints

In our current MVP state, our express endpoints list are small, as the interaction between client and server is small. Below structures how the endpoints work:

Status Verb Route Description
✅ POST /me Creates an account for the user and returns the user's data
✅ GET /me Login given user cookies and verifies the data aligns w/ the server
✅ DELETE /me Removes a user's info from the database
---- ------ --------------------- -------------------------------------------------------------------
✅ POST /lobby Creates a new lobby and returns the lobby id w/ lobby data
✅ GET /lobby Returns the lobbies a user is managing and participating in
---- ------ --------------------- -------------------------------------------------------------------
✅ POST /lobby/:id Join a lobby
✅ PATCH /lobby/:id Update a lobbies information
✅ GET /lobby/:id Get lobby specific info
✅ DELETE /lobby/:id Delete a lobby
✅ DELETE /lobby/:id/user/:id Delete a user from a lobby

Content Types

All content types will be in the application/json form:

Header Parameter Description
Content-Type Always set to application/json

Authentication

Authentication occurs with a JSON Web Token (JWT). JWT let's us cryptographically store the user's id through a hash. This allows us to verify the identity of a user securely, and immediately access their information. See POST /me to see how to get a user's token.

Header Parameter Description
Authorization The token for a user: Bearer TOKEN

POST /me

This POST request serves as a method for a user to login if there is no cookie information stored on the client. When a user successfully logs in, Aurgy will send the client the user's info that will be used to populate the client.

Request Body Parameter Description
refreshToken A user's refresh token

Responses

Status Code Description
200 A user response (detailed below)
403 A bad refresh token

User Response

The response sent to the user if the authentication is successful.

{
  "name": "string",          // The user's name
  "id": "string",            // The user's spotify id
  "accountType": "string",   // The user's spotify plan: premium or free
  "country": "string",       // The user's country code
  "images": "string[]",      // Any links to the user's images
  "jwt": "string"            // the jwt token for the user (lasts 7 days)
}

GET /me

The GET request is a method for the client to verify a user's information through the cookies stored on the client.

Headers Description
Authorization The token for a user: Bearer TOKEN

Responses

Status Code Description
200 A user response (detailed below)
401 Token is not present in headers
403 Token does not pass verification (expired)
404 User is not found in database

User Response

The response sent to the user if the authentication is successful.

{
  "name": "string",          // The user's name
  "id": "string",            // The user's spotify id
  "accountType": "string",   // The user's spotify plan: premium or free
  "country": "string",       // The user's country code
  "images": "string[]",      // Any links to the user's images
}

DELETE /me

The DELETE request is a method for the client to delete their account. This will result in the entire entry for the user to be deleted.

Headers Description
Authorization The token for a user: Bearer TOKEN

Responses

Status Code Description
200 User has been succesfully deleted from database
401 Token is not present in headers
403 Token does not pass verification (expired)
404 User is not found in database

POST /lobby

The POST request for /lobby serves as a way to create a lobby. Aurgy will then return the lobby information. In order to understand who is making the request, we will be sending both the id and the refresh token of the user.

Headers Description
Authorization The token for a user: Bearer TOKEN
Request Body Parameter Description
lobbyName The name of the lobby
theme The theme of the lobby

Responses

Status Code Description
200 User has been succesfully deleted from database
401 Token is not present in headers
403 Token does not pass verification (expired)
404 User is not found in database
406 User has exceeded their lobby count, the name is invalid, or the theme is invalid
500 Failed to create Lobby

Lobby Response

The response sent to the user regarding the lobby information.

{
  "name": "string",      // The lobby name
  "id": "string",        // The lobby id
}

GET /lobby

The GET request for /lobby is a way for the user to get what lobbies they are in.

Headers Description
Authorization The token for a user: Bearer TOKEN

Responses

Status Code Description
200 User has been authenticated and returns the lobbies response
401 Token is not present in headers
403 Token does not pass verification (expired)
404 User is not found in database

POST /lobby/:id

The POST request for /lobby/:id is a way for a user to join a lobby.

Verification happens in two stages:

  1. User verification: make sure the user is valid
  2. Lobby token verification: Make sure the lobby token to join the lobby is valid (not expired)
Headers Description
Authorization The token for a user: Bearer TOKEN
Request Body Parameter Description
lobbyToken The expirable token to verify a lobby

Responses

Status Code Description
200 User has been added to the lobby and the lobby info is sent
401 Token is not present in headers
403 Token does not pass verification (expired)
404 User is not found in database
406 The lobby token is invalid

GET /lobby/:id

The GET request for /lobby/:id is a way for a user to get lobby info. It might be a good idea to turn this into a websocket. That way updates to the lobby when a user is on the page is updated on the client in real time. We can investigate this solution at a later day.

Verification happens in two stages:

  1. User verification: make sure the user is valid
  2. Lobby Status: Make sure the user is part of the lobby
Headers Description
Authorization The token for a user: Bearer TOKEN

Responses

Status Code Description
200 User is in lobby and the lobby data is sent to the user
401 Token is not present in headers
403 Token does not pass verification (expired)
404 User is not found in database
406 User is not part of the lobby

PATCH /lobby/:id

The PATCH request for /lobby/:id is a way for a user to update lobby information.

Verification happens in two stages:

  1. User verification: make sure the user is valid
  2. Lobby Permissions: Make sure the user is the manager of the lobby
Headers Description
Authorization The token for a user: Bearer TOKEN
Request Body Parameter Description
name The lobby name you want

Responses

Status Code Description
200 Lobby has been succesfully updated from database
401 Token is not present in headers
403 Token does not pass verification (expired)
404 User is not found in database
406 User is not a manager of the lobby

DELETE /lobby/:id

The DELETE request for /lobby/:id is a way for a user to delete a lobby.

Verification happens in two stages:

  1. User verification: make sure the user is valid
  2. Lobby Permissions: Make sure the user is the manager of the lobby
Headers Description
Authorization The token for a user: Bearer TOKEN

Responses

Status Code Description
200 Lobby has been succesfully deleted from database
401 Token is not present in headers
403 Token does not pass verification (expired)
404 User is not found in database
406 User is not a manager of the lobby

DELETE /lobby/:id/user:id

The DELETE request for /lobby/:id/user/:id is a way for the manager of a lobby to remove another user from the lobby.

Verification happens in two stages:

  1. User verification: make sure the user is valid
  2. Lobby Permissions: Make sure the user is the manager of the lobby
Headers Description
Authorization The token for a user: Bearer TOKEN

Responses

Status Code Description
200 Lobby has been succesfully deleted from database
401 Token is not present in headers
403 Token does not pass verification (expired)
404 User is not found in database
406 User is not a manager of the lobby

This is a 👀 Tracking Issue