ESFA Backend API

Welcome to the ESFA Backend API documentation. This API provides endpoints for managing game matches, including retrieving match information and submitting match results.

Overview

The ESFA Backend API is a REST API that enables game match management through secure endpoints. All API requests require authentication via Bearer tokens obtained from a separate Authentication Service.

Key Features

Match Retrieval: Get detailed match information including players and their status
Match Completion: Submit final match results with player rankings and scores
Secure Authentication: JWT-based Bearer token authentication
Comprehensive Error Handling: Detailed error responses for troubleshooting

API Base Information

Version: 1.0.0
Authentication: Bearer Token (JWT)
Content Type: application/json
Base URL: Relative to the site hosting this API

Supported Game Codes

The API currently supports various game types identified by game codes:

TTT: Tic-Tac-Toe
Additional game codes as configured in your system

Architecture Overview

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Client App    │───▶│  Auth Service    │───▶│  ESFA Backend   │
│                 │    │                  │    │      API        │
│ 1. Get Token    │    │ 2. Issue Token   │    │ 3. API Calls    │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Authentication Flow

Obtain Token: Request a Bearer token from the Authentication Service using your API credentials
Make API Calls: Include the Bearer token in the Authorization header for all Backend API requests
Token Refresh: Tokens are short-lived; obtain new tokens when expired

Quick Start

To get started with the ESFA Backend API:

Get Your Credentials: Obtain your apiKey and secretKey from your administrator
Authenticate: Use the credentials to get a Bearer token from the Authentication Service
Start Making Calls: Use the token to access protected endpoints

See our Getting Started Guide for detailed step-by-step instructions.

Available Endpoints

Game Match Management

Method	Endpoint	Description
GET	`/api/v1/games/{gameCode}/matches/{matchId}`	Retrieve match and player information
POST	`/api/v1/games/{gameCode}/matches/{matchId}/finish`	Submit final match results

Authentication (External Service)

Method	Endpoint	Description
POST	`/v1/oauth/token/machine`	Obtain Bearer token for API access

Response Format

All successful responses return JSON data. Error responses follow a consistent envelope format for easy parsing and handling.

Success Response Example

{
  "matchId": "a3c6e5f2-1a2b-4c5d-8e9f-0123456789ab",
  "gameCode": "TTT",
  "players": [
    {
      "id": "p1",
      "name": "Alice", 
      "status": "Active",
      "imgAvatarUrl": "https://api.dicebear.com/9.x/adventurer/svg?seed=Alice"
    }
  ]
}

Error Response Example

{
  "errors": [
    {
      "i18N": "MATCH_NOT_FOUND",
      "error": "Match not found",
      "type": "NotFound"
    }
  ]
}

Getting Help

API Reference: Detailed endpoint documentation with examples
Troubleshooting: Common issues and solutions
OpenAPI Spec: Machine-readable API specification
Code Examples: Sample implementations in various languages

Ready to get started? Check out our Getting Started Guide or jump directly to the Authentication section.

05 September 2025