Path parameters

None

Query parameters

name	allowed value	required	description
test	yes	false	Query will be performed on test data for simulation, no change to real game data, user score / number of tries etc.

Headers

name	type	data type	description
Authorization	Bearer token	string	Authorization token copied from the UI

Responses

http code	content-type	response
200	application/json; charset=utf-8	FireResponse
400	application/json; charset=utf-8	{"error": "Max tries already reached"}
400	application/json; charset=utf-8	{"error": "Invalid query parameter or query parameter value supplied"}
403	application/json; charset=utf-8	{"error": "Unauthorized"}

Example cURL

 curl --request GET --url https://europe-west1-ca-2023-dev.cloudfunctions.net/battleshipsApi/fire --header 'Authorization: Bearer $token'

Path parameters

name	data type	required	description
row	integer	true	vertical position on the board from range [0,11]
column	integer	true	horizontal position on the board from range [0,11]

Query parameters

name	allowed value	required	description
test	yes	false	Query will be performed on test data for simulation, no change to real game data, user score / number of tries etc.

Headers

name	type	data type	description
Authorization	Bearer token	string	Authorization token copied from the UI

Responses

http code	content-type	response
200	application/json; charset=utf-8	FireResponse
400	application/json; charset=utf-8	{"error": "Max tries already reached"}
400	application/json; charset=utf-8	{"error": "Invalid values for row or column"}
400	application/json; charset=utf-8	{"error": "Invalid query parameter or query parameter value supplied"}
403	application/json; charset=utf-8	{"error": "Unauthorized"}

Example cURL

 curl --request GET --url https://europe-west1-ca-2023-dev.cloudfunctions.net/battleshipsApi/fire/:row/:column --header 'Authorization: Bearer $token'

Path parameters

name	data type	required	description
row	integer	true	vertical position on the board from range [0,11]
column	integer	true	horizontal position on the board from range [0,11]
avenger	string	true	use the power of specified avenger (hulk, ironman or thor)

Avenger abilities explained

• thor ability will hit 10 random map points at maximum (at maximum = if there are fewer untouched map points available than 10, all of them will be targeted by this ability)
• ironman ability will return 1 map point of the smallest non-destroyed ship, this map point will be unaffected (the purpose of this ability is to give a hint to the user)
• hulk ability will destroy the whole ship if the map point specified by the row/column combination at the api endpoint hits the ship (all the map points belonging to this ship will be marked as destroyed)

Query parameters

name	allowed value	required	description
test	yes	false	Query will be performed on test data for simulation, no change to real game data, user score / number of tries etc.

Headers

name	type	data type	description
Authorization	Bearer token	string	Authorization token copied from the UI

Responses

http code	content-type	response
200	application/json; charset=utf-8	AvengerFireResponse
400	application/json; charset=utf-8	{"error": "Max tries already reached"}
400	application/json; charset=utf-8	{"error": "Invalid values for row or column"}
400	application/json; charset=utf-8	{"error": "Invalid value for avenger"}
400	application/json; charset=utf-8	{"error": "Avenger unavailable"}
400	application/json; charset=utf-8	{"error": "Invalid query parameter or query parameter value supplied"}
403	application/json; charset=utf-8	{"error": "Unauthorized"}

Example cURL

 curl --request GET --url https://europe-west1-ca-2023-dev.cloudfunctions.net/battleshipsApi/fire/:row/:column/avenger/:avenger --header 'Authorization: Bearer $token'

Path parameters

None

Query parameters

name	allowed value	required	description
test	yes	false	Query will be performed on test data for simulation, no change to real game data, user score / number of tries etc.

Headers

name	type	data type	description
Authorization	Bearer token	string	Authorization token copied from the UI

Responses

http code	content-type	response
200	application/json; charset=utf-8	{"availableTries": number }
400	application/json; charset=utf-8	{"error": "Max tries already reached"}
400	application/json; charset=utf-8	{"error": "No ongoing game found"}
400	application/json; charset=utf-8	{"error": "Invalid query parameter or query parameter value supplied"}
403	application/json; charset=utf-8	{"error": "Unauthorized"}

Example cURL

 curl --request GET --url https://europe-west1-ca-2023-dev.cloudfunctions.net/battleshipsApi/reset --header 'Authorization: Bearer $token'

name	data type	description
grid	string	144 chars (12x12 grid) representing updated state of map, '*' is unknown, 'X' is ship, '.' is water.
cell	string	Result after firing at given position ('.' or 'X'). This field may be empty ('') if player calls /fire endpoint or tries to fire at already revealed position.
result	boolean	Denotes if fire action was valid. E.g. if player calls /fire endpoint or fire at already revealed position, this field will be false.
avengerAvailable	boolean	Avenger availability after the player's move.
mapId	integer	ID of the map, on which was called last player's move. This value will change when player beats current map.
mapCount	integer	Fixed number of maps which are required to complete before completing one full game.
moveCount	integer	Number of valid moves which were made on the current map. Invalid moves such as firing at the same position multiple times are not included.
finished	boolean	Denotes if player successfully finished currently ongoing game => if player completed mapCount maps. Valid move after getting true in this field results in new game (or error if player has already achieved max number of tries).
lastGameMoves	integer?	If game is finished then number of moves is included in the response, otherwise this field is not included.

Example

{
    "grid": "*...**********************XX.**********************************.***********.***********.***********************************************.********",
    "cell": "X",
    "result": true,
    "avengerAvailable": false,
    "mapId": 0,
    "mapCount": 2,
    "moveCount": 10,
    "finished": false
}

AvengerFireResponse includes all the fields from FireResponse and adds the following

name	data type	description
avengerResult	{mapPoint: {x: integer, y: integer }, hit: boolean}[]	mapPoint's values x (row) and y (column) denote coordinates which were affected by avenger ability. Value of hit denotes, if coordinates specified by mapPoint have hit a ship.

Example

{
    "grid": "*...**********************XX.****..****************************.***********.***********.***********************************************.********",
    "cell": ".",
    "result": true,
    "avengerAvailable": false,
    "mapId": 0,
    "mapCount": 2,
    "moveCount": 12,
    "finished": false,
    "avengerResult": [
        {
            "mapPoint": {
                "x": 9,
                "y": 2
            },
            "hit": false
        }
    ]
}