👀 Tracking: available functional apis for aurgy backend

[BryanPan342]

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