Skip to content

API.md

Latest commit

 

History

History
301 lines (245 loc) · 5.05 KB

API.md

File metadata and controls

301 lines (245 loc) · 5.05 KB
Raw

API Documentation

REST API

Base URL: http://localhost:5000

Create Game

POST /api/games

Request Body:

{
  "whitePlayerName": "Alice",
  "blackPlayerName": "Bob"
}

Response:

{
  "gameId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "whitePlayerName": "Alice",
  "blackPlayerName": "Bob",
  "createdAt": "2025-01-15T10:30:00Z"
}

Get Game State

GET /api/games/{gameId}

Response:

{
  "gameId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "InProgress",
  "currentTurn": "White",
  "fullMoveNumber": 1,
  "resultDescription": null,
  "board": {
    "squares": [
      {
        "file": 0,
        "rank": 0,
        "algebraic": "a1",
        "piece": { "type": "Rook", "color": "White" }
      }
    ]
  },
  "moveHistory": []
}

Make Move

POST /api/games/{gameId}/moves

Request Body:

{
  "from": "e2",
  "to": "e4",
  "promotionPiece": null
}

Response (success):

{
  "success": true,
  "errorMessage": null,
  "gameStatus": "InProgress",
  "isCheck": false,
  "resultDescription": null
}

Response (failure):

{
  "success": false,
  "errorMessage": "Illegal move.",
  "gameStatus": "InProgress",
  "isCheck": false,
  "resultDescription": null
}

Get Valid Moves

GET /api/games/{gameId}/valid-moves/{from}

Response:

{
  "from": "e2",
  "validMoves": ["e3", "e4"]
}

Resign Game

POST /api/games/{gameId}/resign

Request Body:

{
  "resigningColor": "White"
}

Response:

{
  "success": true,
  "errorMessage": null,
  "resultDescription": "Black wins by resignation."
}

Offer Draw

POST /api/games/{gameId}/draw

Response:

{
  "success": true,
  "errorMessage": null,
  "resultDescription": "Draw by agreement."
}

SignalR Hub

Endpoint: /gamehub

Client Methods

CreateGame

CreateGame(playerName: string)

Creates a new game and adds the caller to the game group.

Events emitted:

  • GameCreated → CreateGameResult
  • GameStateUpdated → GameStateDto

JoinGame

JoinGame(gameId: Guid, playerName: string)

Joins an existing game group.

Events emitted:

  • PlayerJoined → { GameId, PlayerName }
  • GameStateUpdated → GameStateDto

MakeMove

MakeMove(gameId: Guid, from: string, to: string, promotionPiece?: PieceType)

Makes a move. Uses algebraic notation (e.g., "e2", "e4").

Events emitted (success):

  • MoveMade → MakeMoveResult
  • GameStateUpdated → GameStateDto

Events emitted (failure):

  • MoveRejected → MakeMoveResult

GetValidMoves

GetValidMoves(gameId: Guid, from: string, requestId?: string)

Gets legal moves for a piece at the given position.

Events emitted:

  • ValidMovesReceived → { From, ValidMoves, RequestId }

ResignGame

ResignGame(gameId: Guid, color: Color)

Resigns the game for the given color.

Events emitted:

  • GameResigned → ResignGameResult

OfferDraw

OfferDraw(gameId: Guid, color: Color, action?: DrawAction)

Offer (0), accept (1), or decline (2) a draw.

Events emitted:

  • DrawOffered → OfferDrawResult
  • GameStateUpdated → GameStateDto (on successful draw acceptance)

RequestGameState

RequestGameState(gameId: Guid)

Requests the current game state.

Events emitted:

  • GameStateUpdated → GameStateDto

Server Events

Event Payload Description
GameCreated CreateGameResult New game created
PlayerJoined { GameId, PlayerName } Opponent joined
GameStateUpdated GameStateDto Full game state
MoveMade MakeMoveResult Move executed
MoveRejected MakeMoveResult Move was illegal
ValidMovesReceived { From, ValidMoves, RequestId } Legal moves for a piece
GameResigned ResignGameResult Player resigned
DrawOffered OfferDrawResult Draw offer/accept/decline

DTOs

GameStateDto

{
  "gameId": "Guid",
  "status": "GameStatus",
  "currentTurn": "Color",
  "fullMoveNumber": "int",
  "resultDescription": "string|null",
  "board": "BoardDto",
  "moveHistory": "MoveDto[]"
}

BoardDto

{
  "squares": "SquareDto[]"
}

SquareDto

{
  "file": "int (0-7)",
  "rank": "int (0-7)",
  "algebraic": "string (e.g., 'e4')",
  "piece": "PieceDto|null"
}

PieceDto

{
  "type": "PieceType (Pawn|Rook|Knight|Bishop|Queen|King)",
  "color": "Color (White|Black)"
}

MoveDto

{
  "from": "string (algebraic)",
  "to": "string (algebraic)",
  "moveType": "MoveType",
  "promotionPiece": "PieceType|null"
}

Enums

GameStatus

NotStarted | InProgress | Check | Checkmate | Stalemate | Draw | Resigned | TimeOut

Color

White | Black

PieceType

Pawn | Rook | Knight | Bishop | Queen | King

MoveType

Normal | Capture | Castling | EnPassant | Promotion | KingSideCastling | QueenSideCastling

DrawAction

Offer (0) | Accept (1) | Decline (2)