chesslablab / chess-api Goto Github PK

The POST /api/play/rav endpoint has recently been implemented and now is to be documented at Chess API.

See:

• #67

Thus, a new entry in the mkdocs.yml file needs to be added as well as its corresponding file in the docs folder.

Keep it up and happy learning!

Update the Chess API to Symfony 6.3.4.

Keep it up,

This is the very first REST API endpoint to be added as per the specification below.

Query example:

curl -d '{"movetext":"1.e4"}' -H "Content-Type: application/json" -X POST http://localhost:8000/api/play

Response 200 (OK):

{
  "fen": "rnbqkbnr/pppppppp/8/8/4P3/8/PPPP1PPP/RNBQKBNR b KQkq e3",
  "isCheck": false,
  "isMate": false,
  "movetext": "1.e4"
}

At this moment the POST /api/play endpoint is partially implemented in src/Controller/PlayController.php, however, in order for it to respond with a 400 status code, the Chess\Player class should first throw an exception if provided with a wrong movetext.

See:

• chesslablab/php-chess#173

Keep it up, and happy learning!

The GET /api/annotations/games endpoint has recently been implemented and now is to be documented at Chess API.

See:

• #51

Thus, a new entry in the mkdocs.yml file needs to be added as well as its corresponding file in the docs folder.

Keep it up and happy learning!

See chesslablab/php-chess#365

At this moment, src/Controller/DownloadImageController.php doesn't allow to download screenshots of Capablanca chess games as shown in the animation below.

However, the /download_image endpoint should accept a new parameter called variant, this way a new $board object can be created accordingly to be then passed to Chess\Player\PgnPlayer.

For further information on how a $board is initialized please visit:

• php-chess/tests/unit/Variant/Capablanca80/BoardTest.php

This issue is quite similar to the following one which has been solved already:

• #24

Remember:

There is an easy quick way to get the API up and running without an SSL certificate for when testing endpoints that don't require a database connection, e.g., api/download_image or api/download_mp4. In such cases you may want to use PHP's built-in web server.

Keep it up, and happy coding and learning!

This endpoint is intended to play chess against the Stockfish chess engine and is to be implemented as described next.

The POST /api/engine/stockfish endpoint should be implemented in a new file called src/Controller/EngineStockfishController.php.

See:

• Chess\UciEngine\Stockfish
• Chess\Player\LanPlayer

Keep it up, and happy learning and coding!

Annotated games are games with comments that help understand what is going on the chessboard. They usually include variations showing the development of the game in selected positions that require an in-depth understanding. RAV stands for Recursive Annotation Variation. This is the standard format for annotated chess games.

Figure 1. Click on Database > Annotated Games and select a chess game.

Figure 2. Read the comments and explore the variations.

At this moment, the annotated games are being added to the data/annotations/games.json file. While the chess games database contains one million records, there are only a few annotated chess games. This is mainly because annotations may be subject to copyright.

Described next are the games to be added.

World Chess Championship 1921

World Chess Championship 1921. (2023, August 9). In Wikipedia. https://en.wikipedia.org/wiki/World_Chess_Championship_1921

• #69
• #70
• #71
• #72

© Copyrighted Annotations

Copyright permissions have been obtained from the authors to get annotated chess games published into chesslablab.com. Should you publish these games into your fork of ChesslaBlab, please also ask the authors for copyright permissions.

• #95
• #96
• #98
• #99
• #100
• #116

World Chess Championship 2004

• #102
• #103
• #104
• #105
• #106
• #107
• #108
• #109
• #110
• #111
• #112
• #113
• #114
• #115

See chesslablab/spablab#376

Figure 1. Click on Database Search

Figure 2. Enter "foobar" in the SAN Movetext text field.

The API endpoint should respond with a 204 HTTP status code.

Happy coding and learning!

The GET /autocomplete endpoint has proven to be not optimal with about one million chess games in the database. The autocomplete JSON files combined take up 1.5 MB as shown in the image attached.

Thus, the src/Controller/AutocompleteController.php file needs to be split into two controllers:

• src/Controller/AutocompleteEventsController.php
• src/Controller/AutocompletePlayersController.php

This issue is intended to implement src/Controller/AutocompleteEventsController.php.

Happy coding!

The MP4 video is not downloaded if playing a game after a FEN string has been previously loaded.

In the screenshot attached below the follwing FEN string is loaded:

4k2r/pp1b1pp1/8/3pPp1p/P2P1P2/1P3N2/1qr3PP/R3QR1K w k -

Then, this sequence of moves is played:

1.Rb1 Qa2 2.Ra1 Qb2

If trying to download the video though, the api/download_mp4 endpoint will respond with a status code 500.

Figure 1. Download a video

Keep it up, and happy coding and learing!

Let's upload the very first chess game in JSON format into IPFS! Any of the games in data/annotations/games.json should be okay. Let's start with the following one.

{
    "Event": "Steinitz - Zukertort World Championship Match",
    "Site": "New Orleans, LA USA",
    "Date": "1886",
    "White": "Johannes Zukertort",
    "Black": "Wilhelm Steinitz",
    "WhiteElo": "?",
    "BlackElo": "?",
    "Result": "0-1",
    "ECO": "D50",
    "movetext": "{ Adapted notes, originally by Robert James Fischer from a television interview. } 1.d4 d5 2.c4 e6 3.Nc3 Nf6 4.Bg5 Be7 5.Nf3 O-O 6.c5 { is a mistake already; instead it should be played e3, naturally. } 6...b6 7.b4 bxc5 8.dxc5 a5 9.a3 d4 { is a fantastic move; it's the winning move. The pawn can't be taken with the knight because of axb4. } 10.Bxf6 gxf6 11.Na4 e5 { because the center is easily winning. Black's kingside weakness is nothing. } 12.b5 Be6 { with the idea of dominating the game with a powerful mobile center. } 13.g3 c6 14.bxc6 Nxc6 15.Bg2 Rb8 { threatening Bb3. } 16.Qc1 d3 17.e3 e4 18.Nd2 f5 19.O-O Re8 { is a very modern move; a quiet positional move. The rook is doing nothing now, but later... } 20.f3 { to break up the center, it's the only chance for White. } 20...Nd4 21.exd4 Qxd4+ 22.Kh1 e3 (22... Qxa4 { allows Black to easily regain material. }) 23.Nc3 Bf6 24.Ndb1 d2 25.Qc2 Bb3 26.Qxf5 d1=Q 27.Nxd1 Bxd1 28.Nc3 e2 29.Raxd1 Qxc3 { and White resigns. The center has prevailed. } 0-1"
  }

See https://github.com/orgs/chesslablab/discussions/349

Keep it up,

The README.md should describe how to run the Docker containers as well as elaborate on how to test the API endpoints.

Happy coding and keep it up.

Add this game to the data/annotations/games.json file.

The GET /autocomplete endpoint has proven to be not optimal with about one million chess games in the database. The autocomplete JSON files combined take up 1.5 MB as shown in the image attached.

Thus, the src/Controller/AutocompleteController.php file needs to be split into two controllers:

• src/Controller/AutocompleteEventsController.php
• src/Controller/AutocompletePlayersController.php

This issue is intended to implement src/Controller/AutocompletePlayersController.php.

Happy coding!

Implement an endpoint to convert an image into a FEN string.

See:

• Chess Piece Image Recognizer
• src/Media/FEN/Field/JpgToPiecePlacement.php

Keep it up, and happy coding!

This endpoint is intended to fetch the name of a chess opening given its ECO code.

Query examples:

curl -d '{"eco":"B94"}' -H "Content-Type: application/json" -X POST http://localhost:8000/api/eco

Response:

{
  "name": "Sicilian, Najdorf"
}

The POST /api/eco endpoint should be implemented in a new file called src/Controller/EcoController.php.

Keep it up, and happy learning!

This endpoint is intended to fetch chess opening data given a set of parameters.

Query examples:

curl -d '{"eco":"B94"}' -H "Content-Type: application/json" -X POST http://localhost:8000/api/opening

Response:

{
  "eco": "B94",
  "name": "Sicilian Defense: Najdorf Variation",
  "movetext": "1.e4 c5 2.Nf3 d6 3.d4 cxd4 4.Nxd4 Nf6 5.Nc3 a6 6.Bg5"
}

The POST /api/opening endpoint should be implemented in a new file called src/Controller/OpeningController.php.

Add this game to the data/annotations/games.json file.

This endpoint will return an ASCII representation of a chess position, and is to be implemented as per the specification below.

Query examples:

curl -d '{"fen":"rnbqkbnr/pppp1ppp/8/4p3/4P3/8/PPPP1PPP/RNBQKBNR w KQkq e6"}' -H "Content-Type: application/json" -X POST http://localhost:8000/api/ascii

Response:

{
  "ascii":"r  n  b  q  k  b  n  r ... R  N  B  Q  K  B  N  R"
}

The POST /api/ascii endpoint should be implemented in a new file called src/Controller/AsciiController.php.

See:

• https://php-chess.readthedocs.io/en/latest/ascii/#printboard-board-string

Keep it up, and happy coding.

At this moment, the POST api/play endpoint in src/Controller/PlayController.php will respond with a 500 Internal Server Error HTTP status code if processing an invalid movetext as shown in the image below.

Figure 1. API responding with 500 Internal Server Error after 1.e4 e4 has been processed.

However, it should respond with a 400 Bad Request HTTP status code.

The server cannot or will not process the request due to an apparent client error (e.g., malformed request syntax, size too large, invalid request message framing, or deceptive request routing).

Keep it up and happy coding and learning!

This endpoint is intended to download a GIF animation given a movetext, and is to be implemented as per the specification below.

The POST /api/download_gif endpoint should be implemented in a new file called src/Controller/DownloadGifController.php.

See:

• https://php-chess.readthedocs.io/en/latest/media-board-to-gif/

Keep it up, and happy learning!

At the present moment, the POST /api/play endpoint is returning an HTML document when a 400 Bad Request occurs because of a thrown exception; however, a JSON response should be returned instead.

Figure 1. The POST /api/play endpoint should respond with a JSON string.

See:

• #1

Keep it up, and happy learning and coding!

The Documentation shouldn't be published from the chesslablab/website repo but from the chesslablab/chess-api repo using Read the Docs similarly as with the chesslablab/php-chess repo.

Keep it up, and happy learning!

At this moment, a chess server is running on pchess.net — a micro instance on AWS EC2 — which is the sandbox environment for development and testing, and a new issue was opened recently to install and set up a chess database on this machine by the way.

Nginx should be installed as well to host the REST API.

Thus, three different services are intended to run on pchess.net:

• A chess server (WebSocket, port 8443)
• A chess database (MySQL, port 3336)
• A web server (HTTPS, 443)

See:

• chesslablab/chess-data#9

Happy learning, and keep it up.

This endpoint is intended to replace the RAV processing implemented in the chess server.

See:

• src/Command/StartCommand.php

<?php

namespace ChessServer\Command;

// ...

class StartCommand extends AbstractCommand
{
    // ...

    public function run(Socket $socket, array $argv, ConnectionInterface $from)
    {
        if (FenMode::NAME === $argv[2]) {
          // ...
        } elseif (SanMode::NAME === $argv[2]) {
          // ...
        } elseif (RavMode::NAME === $argv[2]) {
            try {
                $settings = (object) json_decode(stripslashes($argv[3]), true);
                if ($argv[1] === Game::VARIANT_960) {
                    $startPos = str_split($settings->startPos);
                    $board = new Chess960Board($startPos);
                    if (isset($settings->fen)) {
                        $board = FenToBoard::create($settings->fen, $board);
                    }
                    $ravPlay = new RavPlay($settings->movetext, $board);
                } elseif ($argv[1] === Game::VARIANT_CAPABLANCA) {
                    $board = new CapablancaBoard();
                    if (isset($settings->fen)) {
                        $board = FenToBoard::create($settings->fen, $board);
                    }
                    $ravPlay = new RavPlay($settings->movetext, $board);
                } else {
                    $board = new ClassicalBoard();
                    if (isset($settings->fen)) {
                        $board = FenToBoard::create($settings->fen, $board);
                    }
                    $ravPlay = new RavPlay($settings->movetext, $board);
                }
                $ravPlay->validate();
                $board = $ravPlay->getBoard();
                $sanMode = new SanMode(new Game($argv[1], $argv[2]), [$from->resourceId]);
                $game = $sanMode->getGame()->setBoard($board);
                $sanMode->setGame($game);
                $socket->getGameModeStorage()->set($sanMode);
                return $socket->sendToOne($from->resourceId, [
                    $this->name => [
                        'variant' => $argv[1],
                        'mode' => $argv[2],
                        'turn' => $game->state()->turn,
                        'filtered' => $ravPlay->getRavMovetext()->filtered(),
                        'movetext' => $ravPlay->getRavMovetext()->main(),
                        'breakdown' => $ravPlay->getRavMovetext()->getBreakdown(),
                        'fen' => $ravPlay->getFen(),
                        ...($argv[1] === Game::VARIANT_960
                            ? ['startPos' =>  $settings->startPos]
                            : []
                        ),
                    ],
                ]);
            } catch (\Throwable $e) {
                return $socket->sendToOne($from->resourceId, [
                    $this->name => [
                        'variant' => $argv[1],
                        'mode' => $argv[2],
                        'message' => 'This PGN movetext could not be loaded.',
                    ],
                ]);
            }
        } elseif (PlayMode::NAME === $argv[2]) {
            // ...
        } elseif (StockfishMode::NAME === $argv[2]) {
            // ...
        }
    }
}

The POST /api/play/rav endpoint is to be implemented in a new file called src/Controller/PlayRavController.php according to the following specification.

Keep it up, and happy learning and coding!

An object-relational mapper (ORM) should be installed to allow the chess API to connect and query the chess database.

See:

• chesslablab/chess-data#9

Keep it up, and happy coding.

This endpoint will allow users to play like a grandmaster by checking out if a given chess game has already been played before by a grandmaster. Probably this is more of a training tool than anything else; if a particular move isn't found in the database, it means it hasn't been played before as per the current information available, which may suggest it's not a good one to make, or more simply, a new line of multiple possible variants out there is being played.

Figure 1. This line was not found in the grandmaster database.

The POST /api/grandmaster endpoint should be implemented in a new file called src/Controller/GrandmasterController.php.

See:

• chesslablab/spablab#194
• chesslablab/chess-data#9
• #5

Keep it up, and happy coding!

The POST api/play endpoint in src/Controller/PlayController.php should also process movetexts in LAN format. In order for this issue to be resolved though, the Chess\Player\LanPlayer class must be implemented first in the PHP Chess repository.

See:

• chesslablab/php-chess#259

Keep it up, and happy coding and learning!

This endpoint is intended to take a heuristic picture of a chess position, and is to be implemented as per the specification below.

Query examples:

curl -d '{"fen":"rnbqkbnr/pp3ppp/4p3/2ppP3/3P4/2P2N2/PP3PPP/RNBQKB1R b KQkq -"}' -H "Content-Type: application/json" -X POST http://localhost:8000/api/heuristic_picture

Response:

{
  "fen": "rnbqkbnr/pp3ppp/4p3/2ppP3/3P4/2P2N2/PP3PPP/RNBQKB1R b KQkq -",
  "heuristicPicture": [ ... ],
  "dimensions": [ ... ]
}

The POST /api/heuristic_picture endpoint should be implemented in a new file called src/Controller/HeuristicPictureController.php.

See:

• https://php-chess.readthedocs.io/en/latest/heuristic-picture/

Keep it up, and happy learning!

See chesslablab/chess-server#179

The information about the round should be described in its own column in data/annotations/games.json.

Keep it up,

A new parameter called flip should be added to allow downloading an image using the POST /download_image endpoint.

The flip parameter is mandatory, and its value must be set in DownloadImageController.php to either w or b in order to flip the board accordingly.

For further information please read:

• Docs » Chess\Media\BoardToPng
• ChesslaBlab Reference Guide

Add this game to the data/annotations/games.json file.

This endpoint is intended to replace the /heuristics command implemented in the chess server.

See:

• /heuristics
• src/GameMode/AbstractMode.php

The POST /api/heuristics endpoint is to be implemented in a new file called src/Controller/HeuristicsController.php according to the following specification.

Keep it up, and happy learning and coding!

See chesslablab/spablab#374

See chesslablab/spablab#534

Add this game to the data/annotations/games.json file.

A new parameter called flip should be added to allow downloading a video using the POST /download_mp4 endpoint. The flip parameter is mandatory, and its value must be set in DownloadMp4Controller.php to either w or b in order to flip the board accordingly. See #39.

For further information please read:

• Docs » Chess\Media\BoardToPng
• ChesslaBlab Reference Guide

The Chess API has recently been updated:

• #24
• #27

Attached below are some examples of the newest version up and running.

Figure 1. POST https://pchess.net/api/grandmaster

Figure 2. POST https://pchess.net/api/download_image

The swagger.yaml file should be proofread and updated accordingly. The API controller methods are found in the src/Controller folder.

This is the sandbox API for testing purposes:

• https://pchess.net/api/docs

Should you find a bug or something that needs to be upgraded, please open an issue.

Keep it up, and happy coding and learning!

See:

• chesslablab/spablab#517
• chesslablab/php-chess#341

A swagger file should be added to the codebase in order to document the REST endpoints as they are created. For example, the first endpoint to be documented is POST /api/play — once the corresponding issue has been successfully closed.

See:

• https://github.com/chesslablab/chess-api/issues
• https://editor.swagger.io/

Keep it up, and happy learning and coding!

See chesslablab/spablab#387

This endpoint is intended to download a PNG image given a FEN string, and is to be implemented as per the specification below.

The POST /api/download_image endpoint should be implemented in a new file called src/Controller/DownloadImageController.php.

See:

• https://php-chess.readthedocs.io/en/latest/media-board-to-png/

Keep it up, and happy learning!

ChessApi\Controller\HeuristicsController should process an optional parameter called fen intended for specific chess positons.

Keep it up, and happy coding!

This endpoint is intended to fetch all annotated games in data/annotations/games.json.

It returns JSON data from a file in a similar way as with:

• GET /autocomplete
• GET /stats/opening

Thus, a new controller called ChessApi\Controller\AnnotationsGames needs to be created, and its code should be quite similar to the following:

• ChessApi\Controller\AutocompleteController
• ChessApi\Controller\StatsOpeningController

See:

• Chess API for Web Apps

Keep it up, and happy coding!

At this moment, src/Controller/DownloadMp4Controller.php allows to download MP4 videos of classical chess games only as shown below.

However, the /download_mp4 endpoint should accept a new parameter called variant. This way, a new $board object could be created accordingly to be then passed to Chess\Player\PgnPlayer.

In Chess960 games the start position needs to be passed to the endpoint as well.

For further information on how a $board is initialized please visit:

• php-chess/tests/unit/Variant/Chess960/
• php-chess/tests/unit/Variant/Capablanca80/

Keep it up and happy learning and coding!