How lichess-org/api works
Main Components
a. Documentation Generation System
• OpenAPI Specification Files (in doc/specs/)
• Documentation Generator (Redocly, indicated by redocly.yaml)
• Static Documentation Output
b. Example Applications Layer
• OAuth App Examples
• Personal Token Examples
• Tournament Entry Examples
c. API Endpoints Categories (Group these by domain)
• Account Management
• Game Operations
• Tournament Systems
• Bot API
• User Management
• etc.
┌─ Documentation Layer ─────────────────────┐
• OpenAPI Specs → Redocly Generator → HTML │
• ┬────────────────────────┘
• ↓
┌─ API Interface Layer ────────────────────────────────┐
• ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌────────────┐ │
• Account │ │ Games │ │ Users │ │ Challenges │ │
• ┘ └─────────┘ └─────────┘ └────────────┘ │
• ┬────────────────────────────────┘
• ↓
┌─ Example Implementation Layer ──────────────┐
• OAuth Apps | Personal Tokens | Demo Apps │
• ┘
Important Elements to Highlight
a. Documentation Flow:
• How YAML specs are processed
• Validation steps (spectral, lint)
• Documentation generation process
b. API Organization:
• Related endpoints (use the folder structure in doc/specs/tags)
• Relationships between different API domains
• Authentication methods
c. Example Integration:
• How example apps connect to the API
• Demonstrate different auth flows
Additional Details
• A section showing the authentication flows (OAuth, Personal Token)
• Notes about rate limiting and API versioning
• Validation and testing flows
Specific Recommendations
• Numbered sequence indicators for flows
• API versioning information
• Security boundaries
Implementation Notes
• Clear separation between public and authenticated endpoints
• How the documentation integrates with the main Lichess platform
• Where example code fits into the overall architecture