API

Official API documentation

Official API documentation for White Waves, a classic online battleship game.

Anyone can write a White Waves client for any platform: a terminal, an old phone, a smartwatch, a calculator. The API is plain HTTP + JSON. A board is a 100-character string, so you don’t need any special libraries to draw it.

Sections

Basics

Rules

Β  Β 
Board 10Γ—10. x is the column (0–9, shown as A–J), y is the row (0–9, shown as 1–10).
Fleet 10 ships: one of length 4, two of 3, three of 2, four of 1.
Placement Ships are straight (horizontal or vertical) and must not touch each other, not even diagonally.
Turns Players shoot in turns. A hit or a sink gives you another shot, a miss passes the turn.
Sinking When a ship is sunk, all cells around it are revealed as empty.
Timers 90 s to place ships (unplaced fleets are placed randomly), 30 s per turn (on timeout the turn passes). Three timeouts in a row lose the game.
Points Winner +100. Each player gets +10 for every enemy ship they sank.

Writing a client: the whole flow

1. POST /api/login                     -> token
2. POST /api/find-game                 -> game (status "waiting")
   ...repeat every 3-5 s until status is "placing"
   (or subscribe over WebSocket and wait for a push)
3. POST /api/lobby/:id/ready           -> send your ships, or an empty body for a random fleet
4. GET  /api/lobby/:id                 -> poll until status is "playing"
5. while status == "playing":
       if yourTurn: POST /api/lobby/:id/shoot {x, y}
       else:        GET  /api/lobby/:id  (poll every 1-2 s, or use WebSocket)
6. status == "finished"                -> winner is "you" or "opponent"

Every game endpoint returns the same game object, seen from your side. A minimal client only needs to understand that one object.