chesspuzzles/api

Restful and GraphQL API for Chess Puzzles from Lichess

Maintainers

Details

github.com/chesspuzzles/api

Source

Issues

Installs: 0

Dependents: 0

Suggesters: 0

Security: 0

Stars: 0

Watchers: 0

Forks: 0

Open Issues: 0

Type:project

dev-main 2025-04-14 18:17 UTC

Requires

MIT ff6fa84768f8b19c9cfacefaa65d64071de5292e

This package is auto-updated.

Last update: 2025-04-14 18:17:41 UTC

README

A Restful (and GraphQL in future) API for Chess Puzzles. It uses the lichess.org puzzles.

WARNING: This API is still in development and is not ready for production use.

The content below here is generated by Claude 3.7. I will review it later and make changes if needed. There are a few clarifications and details that need to be added.

Table of Contents

API Documentation

I will add a more detailed documentation in a separate repo using Docusaurus.

Endpoints

Puzzles

Method Endpoint Description
GET /v1/puzzles List puzzles with pagination and filtering
GET /v1/puzzles/show/{id} Get a specific puzzle by ID
GET /v1/puzzles/themes Get all available puzzle themes
GET /v1/puzzles/openings Get all available opening tags
GET /v1/puzzles

Returns a paginated list of puzzles with optional filtering.

Query Parameters:

  • limit (int, default: 10): Number of puzzles to return
  • offset (int, default: 0): Pagination offset
  • order_by (string, default: 'PuzzleId'): Field to sort by
  • direction (string, default: 'ASC'): Sort direction ('ASC' or 'DESC')
  • min_rating (int, optional): Minimum puzzle rating
  • max_rating (int, optional): Maximum puzzle rating
  • themes (string, optional): Filter by themes (comma-separated)
  • opening_tags (string, optional): Filter by opening tags (comma-separated)
  • min_popularity (float, optional): Minimum popularity score
  • max_popularity (float, optional): Maximum popularity score
  • min_plays (int, optional): Minimum number of plays

Response:

{
  "data": [
    {
      "PuzzleId": "string",
      "FEN": "string",
      "Moves": "string",
      "Rating": 1500,
      "RatingDeviation": 80,
      "Popularity": 80.5,
      "NbPlays": 1000,
      "Themes": "string",
      "OpeningTags": "string"
    }
  ],
  "meta": {
    "limit": 10,
    "offset": 0,
    "total": 100,
    "order_by": "PuzzleId",
    "direction": "ASC"
  }
}
GET /v1/puzzles/show/{id}

Returns a specific puzzle by ID.

Response:

{
  "PuzzleId": "string",
  "FEN": "string",
  "Moves": "string",
  "Rating": 1500,
  "RatingDeviation": 80,
  "Popularity": 80.5,
  "NbPlays": 1000,
  "Themes": "string",
  "OpeningTags": "string"
}
GET /v1/puzzles/themes

Returns a list of all available puzzle themes.

Response:

[
  "mate",
  "mateIn2",
  "fork",
  "pin",
  "hanging"
]
GET /v1/puzzles/openings

Returns a list of all available opening tags.

Response:

[
  "Sicilian Defense",
  "Queen's Gambit",
  "Ruy Lopez"
]

Authentication

Currently, the API does not require authentication for basic usage. Rate limiting is applied to all requests.

Rate Limiting

NOTE: This feature is not yet implemented.

To prevent abuse, the API implements rate limiting:

  • 60 requests per minute per IP address
  • 1000 requests per day per IP address

Rate limit headers are included in all responses:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1620000000

Self-Hosting Guide

Requirements

  • PHP 8.3 or higher
  • Composer
  • SQLite3/MySQL/MariaDB database [if you do not download the database in releases section and plan to use a different database (you'd need to export it yourself)]
  • Web server (Apache, Nginx, etc.)

Installation

Via Composer

If you have composer installed, you can use the following command to install the application:

composer create-project chesspuzzles/api <directory>

Via Repo

  1. Clone the repository:

    git clone https://github.com/chesspuzzles/api.git
cd lichess-puzzles-api

  2. Install dependencies:

    composer install

  3. Create a database and import the Lichess puzzles data.

  4. Copy the environment sample file and configure it:

    cp env.sample .env

Configuration

No need to configure anything. App should work out of the box.

NOTE: Fix this.

Edit the .env file to configure your database connection and other settings:

DB_HOST=localhost
DB_DATABASE=puzzles
DB_USER=root
DB_PASS=password

APP_ENV=production

Additional configuration options can be found in the config/ directory.

Running the Application

Development

For development, you can use PHP's built-in server:

./console serve

This will start a development server at http://localhost:8000.

Production

For production, configure your web server to point to the public/ directory as the document root.

Development Guide

Architecture

The application follows a simple MVC architecture with League container for dependency injection:

  • Controllers: Handle HTTP requests and responses (src/Controller/)
  • Models: Interact with the database (src/Model/)
  • Services: Contain business logic (src/Service/)
  • Middleware: Process requests before/after they reach controllers (src/Middleware/). Modify request and response objects.

The application uses League container's autowiring functionality, which automatically resolves dependencies without requiring manual configuration in bootstrap.

Adding New Features

Creating a New Controller

Use the built-in command to generate a new controller:

./console make:controller Your

This will create a new controller in src/Controller/ with basic CRUD methods.

Creating a New Model

Use the built-in command to generate a new model:

./console make:model Your

This will create a new model in src/Model/ with basic database operations.

Creating a New Service

Use the built-in command to generate a new service:

./console make:service Your

This will create a new service in src/Service/ with basic methods.

Testing

NOTE: This feature is not yet implemented.

The application uses PHPUnit for testing. To run tests:

./vendor/bin/phpunit

Tests are located in the tests/ directory and follow the same structure as the src/ directory.