Unassigned myself as this is no longer my responsibility. Here is the doc created initially as a first step: https://www.notion.so/waterball/GAAS-Lobby-Service-Documentation-813ec18abbbf4690ab151a516729b895?pvs=4

Reposting the initial Notion documentation notes for transparency:

GAAS Lobby Service Documentation

Error codes: PlatformError.kt
- alphanumeric based error codes
JWT

Game Registration Controller

GET /games

list all registered games

200

A list of games
Game object:

{
    // game id from the register - mongo object id
  "id": "string",
    // the human readable name of the game
  "name": "string", 
    // uri - point to external CDN
  "img": "string",
    // minimum number of players required to start the game
  "minPlayers": 0,
    // maximum number of players allowed to start the game
  "maxPlayers": 0
}

remove 400, and 404 status
Game object

POST /games

create games
- input: a single JSON object that represents the game
game object

{
  // English based unique name used for routing game requests to their respective resources
  // verify field validation
    // required
  "uniqueName": "string",
    // human readable name
  // char length 
    // required
  "displayName": "string",
  // English description of the game
  // verify field validation 
    // required
  "shortDescription": "string",
    // game rule
    // required
  "rule": "string",
  // game image URL
    // required
  "imageUrl": "string",
    // minimum number of players required to start the game
    // required
  "minPlayers": 0,
    // maximum number of players allowed to start the game
    // required
  "maxPlayers": 0
    // cloud hosted frontend absolute URL
    // required
  "frontEndUrl": "string",
    // cloud hosted backend absolute URL
    // required
  "backEndUrl": "string"
}

200 - OK

400

object

{
    "timestamp": "2023-08-18T14:10:17.545Z",
  "errorCode": "string",
  "message": "string"
}

404 - remove, will not happen

PUT /games/{gameId}

Replace game config based on the supplied game id with the supplied game object in request body

Game object (same as POST) - request body

{
  // English based unique name used for routing game requests to their respective resources
  // verify field validation
    // required
  "uniqueName": "string",
    // human readable name
  // char length 
    // required
  "displayName": "string",
  // English description of the game
  // verify field validation 
    // required
  "shortDescription": "string",
    // game rule
    // required
  "rule": "string",
  // game image URL
    // required
  "imageUrl": "string",
    // minimum number of players required to start the game
    // required
  "minPlayers": 0,
    // maximum number of players allowed to start the game
    // required
  "maxPlayers": 0
    // cloud hosted frontend absolute URL
    // required
  "frontEndUrl": "string",
    // cloud hosted backend absolute URL
    // required
  "backEndUrl": "string"
}

errors: 400 - follow POST
404 - when gameId is not found in the table

Health Check Controller

GET /health
- keep alive

OAuth2 Controller

all endpoints are deprecated
all login requests now will go through API gateway
- wait for authentication documentation

Room Controller

GET /rooms

Query parameters

status
- Enum
  - WAITING
    - waiting for players to join room
  - PLAYING
    - game room is currently
page
- room pagination, page starts at 0
- page ≥ 0
perPage
- number of rooms returned per request
- perPage ≥ 0

Response

200
response.body

{
  "rooms": Room[],
  "page": PageMetadata,
}

Room

{
  // mongodb objectid
  "id": "string",
  // name of the room, user defined
  "name": "string",
  // simple game object
  "game": {
        // game id foreign key - corresponds to the registered game list
    "id": "string",
        // game's displayName
    "name": "string"
  },
  // the player who created the room
  "host": {
        // user id foreign key - corresponds to the user table
    "id": "string",
        // user nickname
    "nickname": "string"
  },
  // room host defined maximum number of players
  "maxPlayers": 0,
  // room host defined minimum minimum of players
  "minPlayers": 0,
    // the number of players currently in the room
  "currentPlayers": 0,
  // is the room locked, ie. ture iff the host makes the room private
  "isLocked": true
}

PageMetadata

{
    // the total number of rooms matching the status filter
    "total": 0,
    // the current page corresponding to the requests request
  "page": 0,
    // the current page of the request
  "perPage": 0
}

POST /rooms

create room

request.body

{
  // room name
    // required
  "name": "string",
    // corresponding game id in the registered game list
    // required
  "gameId": "string",
    // room host defined password to enter the game
    // optional
  "password": "string",
    // maximum number of players for the room
    // required
    // validation: the room's maximum number of player cannot be more than the game's allowed maximum number of players
  "maxPlayers": 0,
    // minimum number of players for the room
    // required
    // validation: the room's minimum number of player cannot be more than the game's allowed minimum number of players
  "minPlayers": 0
}

400 - should correspond to the validation errors

404 - delete this

GET /rooms/{roomId}

get rooms by id
path parameter
- roomId: generated mongo objectId

response

200
- response

{
  // mongodb objectid
  "id": "string",
  // name of the room, user defined
  "name": "string",
  // simple game object
  "game": {
        // game id foreign key - corresponds to the registered game list
    "id": "string",
        // game's displayName
    "name": "string"
  },
  // the player who created the room
  "host": {
        // user id foreign key - corresponds to the user table
    "id": "string",
        // user nickname
    "nickname": "string"
  },
    // the players currently in the room
  "players": [
    {
      "id": "string",
      "nickname": "string"
    }
  ],
    // room host defined maximum number of players
  "maxPlayers": 0,
  // room host defined minimum minimum of players
  "minPlayers": 0,
    // the number of players currently in the room
  "currentPlayers": 0,
  // is the room locked, ie. ture iff the host makes the room private
  "isLocked": true
    // Status enum: WAITING, PLAYING
  "status": "string"
}

400 - no such error
404 - game id not found

DELETE /rooms/{roomId}
- delete room from the supplied room Id
- path parameter - roomId
  - the generated mongodb object id for the room
- 204 - delete success
- 400 - validation error, only host can delete room
- 404 - roomId not found
POST /rooms/{roomId}/players
- Player joining the room
- path parameter
  - roomId: generated mongo objectId
- request body
```
{
    // the password set by the room host
    // optional
  "password": "string"
}
```
- 200 - success
  - the response body should not have error code
- 400 - unable to join
  - room has reach maximum number of players set by the room host
  - the room has password and the supplied password is not correct
- 404 - roomId not found
DELETE /rooms/{roomId}/players/{playerId}
- removing player from the room
- path parameter roomId
  - room id
- path parameter playerId
  - user id - corresponding to user table
- 200 - success - player has been removed
  - the response body should not have error code
- 400 - unable to remove player
  - insufficient permission - the initiated user is not room host
- 404 - not found
  - unable to find the specified room
  - unable to find the specified player in the room
DELETE /rooms/{roomId}/players/me
- player self leaving the given room
- if the player is not in the room specified by roomId the request will still succeed
- path parameter roomId
  - room id
- no body
- 204 - success - player has left the room
  - the response body should not have error code
- 404 - not found
  - unable to find the specified room
POST /rooms/{roomId}/players/me:cancel
- players self change status to “not ready” on the UI
- if the player is already “not ready” and calls this endpoint the request will return 200
- there is isReady label that’s not on the swagger doc
  - investigate getRoomViewModel
- path parameter roomId
  - room id
- 200 - successfully changed status to NOT_READY
- 404 - not found
  - roomId not found
POST /rooms/{roomId}/players/me:ready
- players self change status to “ready” on the UI
- if the player is already “ready” and calls this endpoint the request will return 200
- toggle the same field as the cancel endpoint from above
- path parameter roomId
  - room id
- 200 - successfully changed status to NOT_READY
- 404 - not found
  - roomId not found

User Controller

GET /users/me

gets the user’s self information
200 - success
- response.body

{
  // user id - generated mongodb objectid
    "id": "string",
  // user email
  "email": "string",
    // user nick name
  "nickname": "string"
}

400 - will not occur - remove
404 - will not occur - remove

PUT /users

user self change information
request.body

{
    // user desired new nickname
    // uniqueness constraint
    // character length range in [4,16]
    // alphanumeric + zh encoding
    "nickname": "string"
}

200 - success, in response.body

{
  "id": "string",
  "email": "string",
  "nickname": "string"
}

400 - validation failed - see above
404 - will not occur

Game-as-a-Service / Lobby-Platform-Service

Swagger Document Enhancement #150