shooting-event/API_CHANGES.md

API Changes (Not Yet Reflected in backend/openapi/openapi.json)

This document lists additive API changes currently implemented in the Go backend.

Summary

Existing endpoints remain compatible.

Added capabilities:

1. Position board persistence for live/admin ordering.
2. Stage session control (start/end) for event flow.
3. Stage history retrieval.
4. New state fields (positionBoards, current_stage, last_stage).

1) Position Board Endpoint

• Method: PUT
• Path: /api/admin/positions/:board
• Auth: admin bearer token (Authorization: Bearer <token>)

Supported :board values

• preliminary
• final
• prelim_tiebreak
• final_tiebreak

Request body

{
  "slots": [
    { "playerId": 12, "groupKey": "A", "position": 1 },
    { "playerId": 15, "groupKey": "A", "position": 2 },
    { "playerId": 20, "groupKey": "B", "position": 1 }
  ]
}

Fields:

• playerId (integer, required)
• groupKey (string, required)
• position (integer > 0, required)

Notes:

• The request replaces all saved slots for the target board.
• For preliminary, players.group_code is synchronized from groupKey.
• Special value UNASSIGNED maps to empty player group.

Response

• 200 OK with full updated admin state payload.

2) Stage Session Control Endpoints

Start stage

• Method: POST
• Path: /api/admin/stage/start
• Auth: admin bearer token

Request body:

{
  "phase": "preliminary",
  "group": "A",
  "round": 2
}

Rules:

• phase must be one of:
  • preliminary
  • prelim_tiebreak
  • final
  • final_tiebreak
• group validation depends on phase:
  • preliminary: group code string (or UNASSIGNED)
  • final: "1" or "2"
  • tie-break phases: positive numeric string
• round normalization:
  • preliminary: 1..3
  • final: 1..2
  • tie-break phases: always 1
• If another stage is active (started, not ended), API returns 409.

Response:

• 200 OK with full updated admin state payload.

End stage

• Method: POST
• Path: /api/admin/stage/end
• Auth: admin bearer token

Rules:

• Ends the currently active stage by setting ended_at.
• If no active stage exists, API returns 400.

Response:

• 200 OK with full updated admin state payload.

3) Stage History Endpoint

• Method: GET
• Path: /api/admin/stage/history
• Auth: admin bearer token

Response:

{
  "items": [
    {
      "id": 1,
      "phase": "preliminary",
      "group": "A",
      "round": 2,
      "startedAt": "2026-04-30T08:27:13Z",
      "endedAt": "2026-04-30T08:28:01Z"
    }
  ]
}

4) New State Fields

Both endpoints now include these fields:

• GET /api/state
• GET /api/admin/state

{
  "positionBoards": {
    "preliminary": {
      "12": { "groupKey": "A", "position": 1 }
    },
    "final": {
      "12": { "groupKey": "1", "position": 3 }
    },
    "prelim_tiebreak": {},
    "final_tiebreak": {}
  },
  "current_stage": {
    "id": 7,
    "phase": "preliminary",
    "group": "A",
    "round": 2,
    "startedAt": "2026-04-30T09:00:00Z"
  },
  "last_stage": {
    "id": 6,
    "phase": "final",
    "group": "1",
    "round": 1,
    "startedAt": "2026-04-30T08:45:00Z",
    "endedAt": "2026-04-30T08:55:00Z"
  }
}

Notes:

• positionBoards keys are player IDs as strings.
• current_stage is null when no stage is active.
• last_stage is null when no stage session has ever started.
• last_stage is the most recently started session (ended or still active).

Compatibility Impact

• Additive only; existing consumers remain functional.
• Consumers can ignore unknown fields safely.
• Consumers needing control/monitoring can use new stage endpoints and fields.