openapi: 3.0.3
info:
  title: FootViz API
  description: A modernized, database-driven API for the FootViz application.
  version: 2.0.0
servers:
  - url: http://localhost:8000/api
paths:
  /scores:
    get:
      summary: Get League Standings
      description: Returns the league standings for a specific country.
      parameters:
        - name: country
          in: query
          required: true
          description: The country for which to retrieve the standings (e.g., 'uk').
          schema:
            type: string
      responses:
        '200':
          description: An array of team standings.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    position: { type: integer }
                    team_name: { type: string }
                    played: { type: integer }
                    won: { type: integer }
                    drawn: { type: integer }
                    lost: { type: integer }
                    goals_for: { type: integer }
                    goals_against: { type: integer }
                    goal_difference: { type: integer }
                    points: { type: integer }
                    recent_form: { type: string }
        '400':
          description: Bad request, country parameter is missing.

  /league_matches:
    get:
      summary: Get League Matches
      description: Returns all matches for a given country.
      parameters:
        - name: country
          in: query
          required: true
          description: The country for which to retrieve matches (e.g., 'uk').
          schema:
            type: string
      responses:
        '200':
          description: An array of matches.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    result: { type: string, nullable: true }
                    competition: { type: string }
                    match_date: { type: string }
                    team_a: { type: string }
                    team_b: { type: string }
                    goals_a: { type: integer, nullable: true }
                    goals_b: { type: integer, nullable: true }
        '400':
          description: Bad request, country parameter is missing.

  /teams:
    get:
      summary: Get Teams in League
      description: Returns a list of teams for a given country/league.
      parameters:
        - name: country
          in: query
          required: true
          description: The country to retrieve teams from (e.g., 'uk').
          schema:
            type: string
      responses:
        '200':
          description: An array of teams.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    name: { type: string }
                    uri: { type: string, format: uri }
        '400':
          description: Bad request, country parameter is missing.

  /flags:
    get:
      summary: Get All Flags
      description: Returns a list of all countries and their corresponding flag images.
      responses:
        '200':
          description: An array of flags.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    country: { type: string }
                    src: { type: string, format: uri }

  /teams_all:
    get:
      summary: Get All Teams
      description: Returns a list of all teams in the database.
      responses:
        '200':
          description: An array of all teams.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    image_uri: { type: string, format: uri }
                    name: { type: string }
                    slug: { type: string }

  /team_visuals:
    get:
      summary: Get Team Visuals (Legacy)
      description: Returns visualization data for a specific team. Note - this is a legacy endpoint.
      parameters:
        - name: team_id
          in: query
          required: true
          description: The ID of the team to retrieve visuals for.
          schema:
            type: string
      responses:
        '200':
          description: Visualization data for the team.

  /reviews:
    get:
      summary: Get Match Reviews (Legacy)
      description: Returns a list of match reviews. Note - this is a legacy endpoint.
      responses:
        '200':
          description: A list of match reviews.

  /league_team_data:
    get:
      summary: Get League Team Data (Legacy)
      description: Returns data for league-level team visualizations. Note - this is a legacy endpoint.
      responses:
        '200':
          description: A list of league team data.
