Battleships Rest Api Manual

Available calls:

All API calls return a string Result value as the first field in the returned data. Possible values are:

SUCCESS
CALL_ALREADY_IN_PROCESS
WAITING_FOR_GAME
GAME_ALREADY_STARTED
GAME_HAS_ENDED
INVALID_LOGIN_OR_PASSWORD
INVALID_PLAYER_KEY
BOT_IS_SUSPENDED
BOT_IS_INACTIVE
INSUFFICIENT_BALANCE
NOT_YOUR_MOVE
INVALID_MOVE

Get List Of Game Styles

Request to receive the current list of available game styles for the specified GameType as well as the bot’s current balance.

URL: https://19y3lnjoy9.execute-api.eu-west-2.amazonaws.com/prod/GM-GetListOfGameStyles

Parameters:

Name Type Notes
BotId string
BotPassword string
GameTypeId int For battleships this is 51

Return values:

Name Type Notes
Result string
GameStyles Array of GameStyleType
Balance int Bot balance in satoshi

GameStyleType object:

Name Type Notes
GameStyleId int Unique id referring to this game style
GameType int Game type - Value 51 for battleships
Stake int Cost to enter game in satoshi
Prize int Prize awarded to winner of game
GameTypeSpecificInfo JSON GameType specific, for Battleships this is a description, starting board, move time, and number and length of ships to place.

Offer Game

This allows the user to offer to play a game. Either a game will start immediately if there is a suitable opponent waiting to play, or the game offer will be queued on the server to wait for an opponent and the client informed.

URL: https://19y3lnjoy9.execute-api.eu-west-2.amazonaws.com/prod/GM-OfferGame

Parameters:

Name Type Notes
BotId string
BotPassword string
MaximumWaitTime int The server will delay returning a result from this call for up to this number of milliseconds. If an opponent is available or becomes available during this period, the server returns immediately. Valid values are 0 - 5000, default value is 500
GameStyleId int Requested game style id
DontPlayAgainstSameUser boolean If set to true, the server will not start a game against another client which is logged in using a BotId from the same user account as this one.
DontPlayAgainstSameBot boolean If set to true, the server will not start a game against another client which is logged in using the same BotId as this one. [Not currently supported]
OpponentId string If set, server will only start a game against a client logged in with the specified BotId

Return values:

Name Type Notes
Result string If an opponent is available, a game will start immediately, and Result will be SUCCESS , if no suitable opponent is available right now, Result is WAITING_FOR_GAME, and the request is queued.
GameState GameStateType GameStateType is a GameType specific set of values describing the current state of the game. Only defined if a game is starting immediately
PlayerKey string This is a unique code created by the server which should be used in all future calls related to this game offer or resulting game
GameId int This is a unique integer created by the server that identifies the game that has been offered

GameStateType - for GameType 51: Battleships

See the quick reference guide here.

GameStateType - for GameType 53: Noughts and Crosses

See the quick reference guide here.

GameStatus values

Value Notes
STARTING_SOON Game will start shortly
RUNNING Game is in progress
WON Game is over and this client won
WON_BY_TIMEOUT This client won by the other player timing out
LOST This client lost
LOST_BY_TIMEOUT This client lost by timing out
DRAWN The game ended in a draw

Cancel Game Offer

Request to cancel a current GameOffer. This can be called before a game has started to cancel the offer from the server's queue.

URL: https://19y3lnjoy9.execute-api.eu-west-2.amazonaws.com/prod/GM-CancelGameOffer

Parameters:

Name Type Notes
BotId string
BotPassword string
PlayerKey string

Return values:

Name Type Notes
Result string If a game already started before this call was made, the Result value is GAME_ALREADY_STARTED and the GameState of the game is returned. If the game offer can be cancelled, Result is SUCCESS.
GameState GameStateType Only returned if a game has already started, otherwise null

Poll For Game State

Request to receive current game state.

URL: https://19y3lnjoy9.execute-api.eu-west-2.amazonaws.com/prod/GM-PollForGameState

Parameters:

Name Type Notes
BotId string
BotPassword string
MaximumWaitTime int The server will delay returning a result from this call for up to this number of milliseconds. If the client has an out of date game state or the server is waiting for this player to move, the server will return immediately. Otherwise the server will return as soon as the game state changes. If the game state does not change for the whole of this period, the current game state is returned at the end of the period. Valid values are 0 - 5000, default value is 500
PlayerKey string

Return values:

Name Type Notes
Result string If no game has yet been started, Result is WAITING_FOR_GAME. If a game has started, Result is SUCCESS
GameState GameStateType This is only returned if a game is underway or completed

Make Move

Used to send the client's chosen game move to the server.

URL: https://19y3lnjoy9.execute-api.eu-west-2.amazonaws.com/prod/GM-MakeMove

Parameters:

Name Type Notes
BotId string
BotPassword string
PlayerKey string
Move MoveType MoveType is specific for which GameType client is playing

MoveType - for GameType 51: Battleships

See the quick reference guide here.

MoveType - for GameType 53: Noughts and Crosses

See the quick reference guide here.

Return values:

Name Type Notes
Result string
GameState GameStateType The state of the game after the client's move has been processed

Test the API with Postman

You can try out the API using the handy Postman app for Chrome - use this link:

https://www.getpostman.com/apps

Demo API Program

You can find a downloadable Python demo of using the API on our downloads page here:

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License