Skip to content

Documentation

Jump to bottom
Jjampong edited this page Jun 19, 2021 · 21 revisions

API

Description

The API provides a variety of routes that support both the online Blade-based configuration screens as well as the Xamarin-based cross-platform mobile app. The API is used to send data from the configuration screens to the clients and vice versa. In order to achieve client synchronization, data pushing is used as opposed to data polling. Pusher App is used to achieve this goal. The API currently does not support any user authentication platforms using tokens.

Details

  • API language: php ^7.3|^8.0 (Laravel)
  • API structure: REST
  • Security platforms: CSRF tokens, TLS support
  • Supported database engine: MySQL
  • Database setup-structure: Laravel migrations

Routes

UserController@get

Returns information regarding a singular user (user specified by id).

  • Parameters: $user: User
  • Associated Route: GET /api/users/{user}

UserController@store

Creates and stores a new user.

  • Parameters: $request: UserStoreRequest
  • Associated Route: POST /api/users

UserController@update

Updates the location of a user (user specified by id).

  • Parameters: $request: UpdateLocationRequest, $user: User
  • Associated Route: PUT /api/users/{user}

UserController@catchThief

Updates a user's status from 'playing' to 'caught'. (user specified by id).

  • Parameters: $user: User
  • Associated Route: PATCH /api/users/{user}/catch

UserController@update

Updates the location of a user (user specified by id).

  • Parameters: $request: UpdateLocationRequest, $user: User
  • Associated Route: PUT /api/users/{user}

InviteKeyController@get

Returns one of three options regarding invite keys (invite key specified by invite key value):

  1. Error message: "The given invite key is in use"
  2. Error message: "The given key has expired since its parent game has ended"
  3. The given key object as JSON
  • Parameters: $key: InviteKey
  • Associated Route: GET /api/invite-keys/{key}

GameController@get

Returns a game's details (game specified by id).

  • Parameters: $game: Game
  • Associated Route: GET /api/games/{game}

GameController@getUsers

Returns all the users that belong to a game (game specified by id).

  • Parameters: $game: Game
  • Associated Route: GET /api/games/{game}/users

GameController@getUsersWithRole

Returns all non-disconnected, including their roles, that belong to a game (game specified by id).

  • Parameters: $game: Game
  • Associated Route: GET /api/games/{game}/users-with-role

GameController@getUsersWithRoleUnfiltered

Returns all the users, including their roles, that belong to a game (game specified by id).

  • Parameters: $game: Game
  • Associated Route: GET /api/games/{game}/users-with-role-unfiltered

GameController@getLoot

Returns all the loot that belongs to a game (game specified by id).

  • Parameters: $game: Game
  • Associated Route: GET /api/games/{game}/loot

GameController@getInviteKeys

Returns a game's invite keys (game specified by id).

  • Parameters: $game: Game
  • Associated Route: GET /api/games/{game}/invite-keys

GameController@getBorderMarkers

Returns a game's border markers (game specified by id).

  • Parameters: $game: Game
  • Associated Route: GET /api/games/{game}/border-markers

GameController@getNotifications

Returns a game's sent notifications (game specified by id).

  • Parameters: $game: Game
  • Associated Route: GET /api/games/{game}/notifications

GameController@getLogo

Returns a game's logo as 'image/png'. If no logo was specified, this route will return a blank screen instead. (game specified by id).

  • Parameters: $game: Game
  • Associated Route: GET /api/games/{game}/logo

GameController@postNotification

Allows for app-side notifications to be sent back to the server and stored in the database for a specific game. (game specified by id).

  • Parameters: $request: StoreNotificationRequest, $game: Game
  • Associated Route: POST /api/games/{game}/notifications

AppErrorController@store

Stores supplied error in the database (for debugging purposes).

  • Parameters: $request: StoreAppErrorRequest
  • Associated Route: POST /api/app-errors

GameController@updateThievesScore

Updates the thieves team's score for a game. (game specified by id).

  • Parameters: $game: Game, $score: int
  • Associated Route: PATCH /api/games/{game}/thieves-score/{score}

GameController@updatePoliceScore

Updates the police team's score for a game. (game specified by id).

  • Parameters: $game: Game, $score: int
  • Associated Route: PATCH /api/games/{game}/police-score/{score}

LootController@updateGadget

Reduces the amount of gadgets the specified user has of given type and uses the gadget (user and gadget specified by id).

  • Parameters: $user: User, $gadget: Gadget
  • Associated Route: PATCH /api/users/{user}/gadgets/{gadget}

LootController@destroy

Deletes a piece of loot from the database. (loot specified by id).

  • Parameters: $loot: Loot
  • Associated Route: DELETE /api/loot/{loot}

GameController@getLootIcon

Fetches the icon for loot.

  • Associated Route: GET /images/money-bag.png

GameController@getPoliceStationIcon

Fetches the icon for the police station.

  • Associated Route: GET /images/police-badge.png

Configuration Screens

Description

Firstly, the configuration screens allow a game leader to specify certain game details such as game duration or game area. The invite keys for a game are also generated here. After all of the game settings have been set to the game leader's preferred values, a game can be started with the click of a button. Secondly, after a game has been started, the configuration screens provide the game leader with certain game details and interactions, such as an overview of the players' last known locations and buttons for pausing, resuming and ending a game.

Details

  • Configuration screens language: Blade HTML
  • Supported browsers: any

Routes

GameController@index

Returns a view for creating a new game or selecting / deleting an existing game.

  • Parameters: none
  • Associated Route: GET /games

GameController@store

Sends a request to the server to create a new game. Redirects the user to the new game's configuration screen.

  • Parameters: none
  • Associated Route: POST /games

GameController@show

Returns the configuration screen for a game (game specified by name). If a game has already started, this route will redirect the user to the game's in-game configuration page instead.

  • Parameters: $game: Game
  • Associated Route: GET /games/{game_name}

GameController@update

Sends a request to the server to update a game's status (game specified by id).

  • Parameters: $request: UpdateGameStateRequest, $game: Game
  • Associated Route: PUT /games/{game}

GameController@storeMarkers

Sends a request to the server to store specified border markers. This route is not to be called manually, and is instead designed to be called via AJAX.

  • Parameters: $request: StoreBorderMarkerRequest, $game: Game
  • Associated Route: POST /games/{game}/border-markers

GameController@storeLoot

Sends a request to the server to store specified loot. This route is not to be called manually, and is instead designed to be called via AJAX. (game specified by id).

  • Parameters: $request: StoreLootRequest, $game: Game
  • Associated Route: POST /games/{game}/loot

GameController@setPoliceStationLocation

Sends a request to the server to store the police station's location. This route is not to be called manually, and is instead designed to be called via AJAX. (game specified by id).

  • Parameters: $request: UpdatePoliceStationLocationRequest, $game: Game
  • Associated Route: PATCH /games/{game}/police-station

GameController@sendNotification

Sends a request to the server to broadcast a new notification (game specified by id).

  • Parameters: $request: StoreNotificationRequest, $game: Game
  • Associated Route: POST /games/{game}/notifications

GameController@checkPassword

Checks whether or not the supplied password is equal to the game's password (game specified by id).

  • Parameters: $game: Game
  • Associated Route: GET /games/{game}/password

UserController@setSpecialRole

Assigns supplied user the double agent role (user specified by id).

  • Parameters: $request: UpdateSpecialRoleRequest, $user: User
  • Associated Route: PATCH /users/{user}/special-role

GameController@storeGamePreset

Sends a request to the server to store a new preset based on the current game. This route is not to be called manually, and is instead designed to be called via AJAX.

  • Parameters: $request: StorePresetRequest
  • Associated Route: POST /presets

GameController@getPresetLoot

Returns all loot for a game preset. (game preset specified by id).

  • Parameters: $preset: GamePreset
  • Associated Route: GET /presets/{preset}/loot

GameController@clearExistingLoot

Removes all loot for a game. This route is not to be called manually, and is instead designed to be called via AJAX. (game specified by id).

  • Parameters: $game: Game
  • Associated Route: DELETE /games/{game}/loot

GameController@getPresetBorderMarkers

Returns all border markers for a game preset. (game preset specified by id).

  • Parameters: $preset: GamePreset
  • Associated Route: GET /presets/{preset}/border-markers

GameController@clearExistingMarkers

Removes all border markers for a game. This route is not to be called manually, and is instead designed to be called via AJAX. (game specified by id).

  • Parameters: $game: Game
  • Associated Route: DELETE /games/{game}/border-markers

Clone this wiki locally