REST API

Optional server API for shared tournament hosting. Base URL: /api

Overview

The REST API is an optional feature for shared tournament hosting. It enables tournament sharing, browsing, and management across multiple users when deployed to a PHP-enabled web server.

• Optional: The API is not required for core functionality — NewTon DC Tournament Manager works fully offline without it
• Graceful degradation: The app detects server availability at startup; API features simply don't appear if the server isn't reachable
• Disabled by default on public deployments: Set NEWTON_API_ENABLED=false on demo or public-facing instances

Architecture

Server Requirements

• PHP 7.0 or higher (PHP 8.2+ recommended)
• Write permissions to the /tournaments directory
• Web server (nginx, Apache) configured to execute PHP

Docker Deployment (Recommended)

docker run -d \
  --name newton-tournament \
  -p 8080:2020 \
  -v ./tournaments:/var/www/html/tournaments \
  ghcr.io/skrodahl/newton:latest

The Docker image includes Alpine Linux with nginx + PHP 8.2-FPM, all API endpoints pre-configured, and persistent tournament storage via volume mount. See Docker Quick Start for the full setup guide.

Directory Structure

/var/www/html/
├── api/
│   ├── list-tournaments.php
│   ├── upload-tournament.php
│   ├── delete-tournament.php
│   └── relay.php
├── tournaments/
│   └── [tournament JSON files]
└── [application files]

Data Storage

• Tournaments stored as JSON files in /tournaments
• Filename format: {TournamentName}_{YYYY-MM-DD}.json
• Unicode characters in filenames fully supported (å, ä, ö, æ, ø, etc.)
• Files created with 0644 permissions; directory requires 0755

Endpoints

1. List Tournaments

GET /api/list-tournaments.php

Returns a list of all tournaments in the /tournaments directory.

Success response (200):

{
  "tournaments": [
    {
      "filename": "Summer_League_2025-08-15.json",
      "name": "Summer League",
      "date": "2025-08-15",
      "players": 16,
      "status": "completed"
    }
  ],
  "count": 1
}

Returns an empty array if no tournaments exist. Skips files that can't be read or have invalid JSON.

2. Upload Tournament

POST /api/upload-tournament.php

Uploads a tournament JSON file to the server.

Request body:

{
  "filename": "MyTournament_2025-10-02.json",
  "data": { ... tournament object ... }
}

Parameters:

Add ?overwrite=true to the URL to replace an existing file. Without it, uploading to an existing filename returns 409 Conflict.

Success response (200):

{
  "success": true,
  "filename": "MyTournament_2025-10-02.json",
  "path": "/tournaments/MyTournament_2025-10-02.json",
  "message": "Tournament uploaded successfully"
}

Error responses:

3. Delete Tournament

POST /api/delete-tournament.php

Deletes a tournament file from the server.

Request body:

{
  "filename": "MyTournament_2025-10-02.json"
}

Success response (200):

{
  "success": true,
  "filename": "MyTournament_2025-10-02.json",
  "message": "Tournament deleted successfully"
}

Error responses:

4. Relay (Remote Upload)

POST /api/relay.php

Forwards a tournament upload to a remote NewTon instance. Used when the browser can’t make cross-origin requests with basic auth (CORS preflight blocks authenticated OPTIONS requests). PHP handles the remote request server-side — no CORS, no preflight, auth works naturally.

Request body:

{
  "url": "https://newton.example.com/api/upload-tournament.php?overwrite=true",
  "username": "NewTon",
  "password": "tournament",
  "payload": {
    "filename": "MyTournament_2025-10-02.json",
    "data": { ... tournament object ... }
  }
}

Parameters:

The remote server’s response is passed through directly — same status code, same JSON body.

Error responses:

Use case: A local Docker instance backs up tournaments to a remote server with basic auth. The browser talks to the local server (same origin, no CORS), and PHP relays to the remote server with credentials.

CORS

All endpoints include CORS headers:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST
Access-Control-Allow-Headers: Content-Type

For production deployments, restrict Access-Control-Allow-Origin to your specific domain.

Client Integration

Feature Detection

The application detects server availability on page load by calling /api/list-tournaments.php. If the server responds, API features (upload button, shared tournaments list, delete buttons) are shown. If not, they are silently hidden — the app works fully without them.

Conditional UI

• “Backup to Server” button — shown when API responds. Opens a modal with source choice (active tournament or from file) and destination info.
• “Shared Tournaments” section — collapsed by default. Shows tournament count, expands on click. Tournaments not in localStorage show “Import”, those already present show “Re-import”.
• Delete buttons — shown on shared tournaments when config.server.allowSharedTournamentDelete is enabled.

Automatic Backup

When enabled in Global Settings → Server Settings → “Automatically backup tournaments on completion”, the tournament JSON is uploaded to the local server at finalization. If a remote server is configured (Global Settings → Remote Backup), the tournament is also relayed to the remote server. Both uploads are fire-and-forget.

Import Validation

Any file downloaded from the server must pass the Tournament Manager’s import validation before it can be loaded. Files that don’t match the expected tournament structure are rejected by the client — they cannot affect your local tournament data.

Data Format

Tournaments are stored as JSON with the following top-level structure:

{
  "id": 1234567890,
  "name": "My Tournament",
  "date": "2025-10-02",
  "created": "2025-10-02T10:30:00.000Z",
  "status": "completed",
  "bracketSize": 16,
  "players": [ ... ],
  "matches": [ ... ],
  "placements": { "1": 1, "2": 2 },
  "exportedAt": "2025-10-02T15:45:00.000Z"
}

Match IDs follow the format FS-1-1 (Frontside Round 1 Match 1) and BS-FINAL (Backside Final). See the export format for the full schema.

Security

Built-in Protections

• Filename sanitized with basename() — prevents directory traversal
• Rejects filenames containing .., /, \, or null bytes
• JSON encoding validated before writing to disk
• No authentication built in — access control is the operator's responsibility (see Privacy Architecture for the full data model)

Recommended Practices

• Restrict Access-Control-Allow-Origin to your domain in production
• Use HTTPS — terminate TLS at your reverse proxy
• Don't expose the container directly to the public internet without a reverse proxy or VPN
• Consider adding HTTP basic authentication at the nginx/Caddy level for write operations
• Back up the /tournaments directory regularly
• Disable the API entirely with NEWTON_API_ENABLED=false if you don't need sharing

Troubleshooting

Upload Button Doesn't Appear

1. Open the browser console and look for [Shared Tournaments] messages
2. Verify /api/list-tournaments.php returns 200 OK
3. Check NEWTON_API_ENABLED is set to true
4. Verify PHP is executing (not returning raw PHP source code)

502 Bad Gateway

PHP-FPM is not running or misconfigured. Check the nginx fastcgi_pass settings and verify PHP-FPM is running inside the container.

Tournaments Not Appearing

Check that /tournaments exists and is readable (755 for directory, 644 for files). Verify the JSON files are valid.

API Returns 403 Forbidden

NEWTON_API_ENABLED is set to false. Restart the container after changing environment variables.

Tournaments Not Persisting After Restart

Verify the volume mount is configured: -v ./tournaments:/var/www/html/tournaments. Check host directory permissions.

View Container Logs

docker compose logs -f

Access Container Shell

docker compose exec newton-tournament sh