Glicko DB

Routes and integration notes

See the User Interface Help for task-oriented instructions and the English README for installation and configuration.

Table of contents

API status

Completed idempotency outcomes are retained for at least 90 days. New outcomes use UTC for retention; legacy outcomes with unknown timezones remain stored indefinitely to avoid premature expiry.

Submission reviewed_at is null for unreviewed submissions and historical reviews whose timezone is unknown; new web and API reviews expose a UTC timestamp.

The application remains server-rendered, with an authenticated API at /api/v1. The v1 operations are GET /me; player, ranking, match, tournament, participant, round, pairing, standings, and report reads; member result submissions; staff moderation; and tournament commands. GET /api/v1/openapi.json provides the full contract. Every API call requires a bearer token with the operation's scope and the account's current role permission. Create and manage personal tokens from the profile page: administrators choose a token's scopes, while every other account receives the scopes its current roles allow. The old draft paths /api/backup, /api/player, and /api/tournament are not implemented.

Operations are grouped into rollout slices that operators enable independently with API_ENABLED_SLICES; every slice is disabled by default. The slices are docs (OpenAPI), reads, submissions, moderation, tournament_setup (create/configure), tournament_participants, and tournament_rounds (rounds, results, processing). The OpenAPI document names each operation's slice in x-rollout-slice. A disabled slice returns 503 with code api_slice_disabled; a slice listed in API_STAFF_PILOT_SLICES returns 503 with api_pilot_restricted to non-staff accounts. Configuration, rollout order, and rollback are in the README.

Result submissions require Idempotency-Key; moderation decisions and conditional commands use If-Match with the current ETag. Tournament commands require the appropriate scope, permission, and geographic access. PairGo is always unrated and its games appear as pairings, not in individual match feeds. See the v1 contract for each operation’s requirements, limits, and effects.

Administrative actions are HTML form submissions. They require an authenticated session, the appropriate role, and a valid CSRF token. Some asynchronous admin actions return a small JSON redirect response only when the request includes X-Requested-With: XMLHttpRequest; this is an internal browser behavior, not a versioned API contract.

Public GET routes

These pages can be opened without an administrator account:

Path Purpose
/ Home page, rankings summary, statistics, and published news
/rankings Paginated public rankings
/players Player directory and filters
/player/view?id=<player_id> Player profile and match history
/matches Match list and filters
/tournaments Public tournament list
/tournaments/<tournament_id> Public tournament details, pairings, and standings
/tournaments/<tournament_id>/matches/<pairing_id> Public PairGo match details
/reports Period and player reports
/reports/export.csv CSV version of the selected report filters
/reports/export.pdf PDF version of the selected report filters
/category Glicko rating and category information
/sgf-library Public SGF library
/sgf-library/<filename> View metadata for an SGF record
/sgf/<filename> Download an SGF record
/matches/<match_id>/record View the SGF record linked to a match
/matches/<match_id>/sgf Download the SGF record linked to a match
/news/<article_id> Published news article

Most pages accept an optional lang=es, lang=en, or lang=pt query parameter. /rankings accepts country (ISO 3166-1 alpha-3; legacy alpha-2 codes are also recognized), region=latam, and group=u18|women. Omitting region uses the administrator's configured region, initially Latin America; region=all or region= includes all regions. Filters intersect, so a country outside Latin America requires the all-region override when Latin America is the default. GET /api/v1/rankings uses the same configured default and region options; its repeated group filters use OR, whereas web group filters intersect. The u18 group also includes players marked Sub-18 with unknown birth year. Report pages also accept start_date, end_date, and player_id filters; see the user guide for examples.

Tournament visibility and ratings

API player last_active is the most recent played public individual game date, or null if none qualifies. Unrated individual games count; drafts, canceled games, PairGo, byes, absences, and invalid dates do not. GET /api/v1/players?last_active_days=N uses an inclusive cutoff from the application's current date, and sort=activity uses that same date. Web ranking activity filters use the same eligibility. Startup migration backfills existing dates; normal stats refresh and tournament visibility changes keep them current without changing rating eligibility.

Current behavior:

These rules apply to games linked through a tournament pairing; standalone matches continue to count toward ratings. See FUTURE_FEATURES.md for other remaining proposals.

Authentication and member routes

Path Method Access
/admin/login GET, POST Sign in
/admin/register GET, POST Create a member account
/admin/forgot-password GET, POST Request a password-reset link
/admin/reset-password/<token> GET, POST Complete a password reset
/admin/report-results GET, POST Members submit results for their linked player or request a link to a player without an account
/admin/profile GET, POST Authenticated users manage their profile
/admin/logout GET End the current session

Member submissions remain pending until reviewed. They do not affect public matches, ratings, or reports before approval.

Unlinked members post action=request_player_link and player_id through the CSRF-protected Report Results form. Player-link requests share the result moderation page and status filter. POST /admin/player-link-requests/<request_id>/approve and /reject require a Manager for the player's country/region or a global Administrator. Approval atomically links the still-available player, records the review/audit, and invalidates the member's existing sessions/tokens. Repeated or conflicting approvals do not overwrite links. Only one pending request per member is allowed; rejection permits a new request. These are web routes, not API resources.

Administrative route groups

All routes below require a signed-in account and role permissions. The forms and available actions are documented in User Interface Help.

The three staff access levels are Global, Regional, and Country. country_organizer and regional_organizer have Tournament Operations, including player creation through tournaments, editing/deletion, matches, SGF linking, and tournament workflows/imports. country_manager and regional_manager additionally have Data Management: player imports, news, and result moderation. Players and moderation are geographically filtered; a match needs at least one in-scope player, and a tournament an in-scope country. News is shared site-wide content. Country roles require a country (with linked-player fallback); regional roles require an explicit supported region. Incompatible or absent scopes deny geographic access. Administrators have global access.

The menu is organized by task rather than role: Players and competition, Imports and ratings, Content and game records, and Site administration. Permissions are unchanged: all backup operations, /admin/import, ratings/categories, users, audit, settings, and destructive SGF deletion remain administrator-only. Legacy operator and tournament_director accounts migrate to regional_manager and regional_organizer, respectively, assigned Latin America, with session/token invalidation. API reads preserve public visibility; draft tournament reads additionally require a current staff permission and matching geographic scope.

POST routes change application state and should be called through the rendered forms. OpenGotha uploads at either /admin/import or /admin/tournaments show the same review preview before explicit approval; the staged preview is bound to the user, uploaded file, and database state, and expires after 15 minutes. Batch actions require the same role permissions and CSRF protection as their single-item equivalents; tournament batch participant actions also require idempotency keys. Backup, restore, import, deletion, and tournament actions are deliberately not exposed as unauthenticated GET operations.

Integration guidance

For an external integration, use the documented authenticated API operations for available workflows and CSV/PDF report exports for other reports. Do not scrape admin forms or depend on undocumented JSON responses.

Milestones A0-A6 are complete; their procedures and observations are in the operations notes. The roadmap contains only pending proposals and verification. Use GET /api/v1/openapi.json for operation details, parameters, and schemas.

The approved OpenAPI 3.1 contract and its authentication, permission, and wire-format decisions are available in the API v1 contract and machine-readable OpenAPI document. Use a personal token with the exact scope named by each operation; tokens are sent only in the Authorization header over HTTPS. Under a path prefix such as /glicko, use the prefixed URLs returned in Location and in the OpenAPI servers entry.

Example request (PowerShell; keep the token in an environment variable, never in the URL):

$headers = @{ Authorization = "Bearer $env:GLICKO_API_TOKEN" }
Invoke-RestMethod -Uri "https://example.org/api/v1/rankings?per_page=5" -Headers $headers

To verify a deployment, run the standard-library smoke client with a pilot token. It sends only side-effect-free probes unless --write-draft-tournament is given, which creates one draft and should be used only against disposable data:

$env:GLICKO_API_TOKEN = "<pilot token>"
python scripts/api_smoke_test.py --base-url https://example.org --expect-enabled docs,reads --expect-disabled submissions,moderation,tournament_setup,tournament_participants,tournament_rounds

It prints a JSON report and exits with 0 when every check passes, 1 when a check fails, and 2 for invalid usage.

^