openapi: 3.0.1
info:
  title: Court Admin / MultiBall Admin API
  description: |
    Back to our login page
    [http://courtadmin.net](http://courtadmin.net)
    # Introduction
    The CourtAdmin API is built on HTTP. Our API is RESTful. It has predictable resource URLs. 
    It returns HTTP response codes to indicate errors and accepts and returns JSON in the HTTP body.
    You can use your favorite HTTP/REST library for your programming language to use CourtAdmin's API,
    or you can request for one of our SDKs.

    # Authentication
    [https://en.wikipedia.org/wiki/Basic_access_authentication](Basic authentication) is a simple authentication scheme 
    built into the HTTP protocol. The client sends HTTP requests with the *Authorization* header that 
    contains the word *Basic* followed by a space and a base64-encoded string *username:password*. 
    For example, to authorize as *demo / p@55w0rd* the client would send the header `Authorization: Basic ZGVtbzpwQDU1dzByZA==`.

  termsOfService: http://courtadmin.net/terms/
  contact:
    email: api@lymb.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0

servers:
  - url: https://courtadmin.net/api/v1.0
    description: Production environment

security:
  - basicAuth: []

tags:
  - name: Courts
    description: Court API Endpoints
  - name: Games
    description: Game API Endpoint
  - name: Statistics
    description: Court Statistics API Endpoint
  - name: Callback events
    description: Messages that our server send to your endpoint (game or court related)

x-tagGroups:
  - name: General
    tags:
      - Courts
      - Games
      - Statistics
      - Callback events

paths:
  /courts:
    get:
      tags:
        - Courts
      summary: Get user assigned courts
      description:
        Make a GET request to this resource to retrieve the list of all
        user courts.
      operationId: getAllCourts
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CourtsResponse"
        400:
          description: Bad Request
          content: {}

  /courts/{courtId}:
    get:
      tags:
        - Courts
      summary: Get court info and status
      description: Get court info and status
      operationId: getCourtDetail
      parameters:
        - name: courtId
          in: path
          description: Database ID for court.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CourtStatusResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
  /courts/{courtId}/games:
    get:
      tags:
        - Courts
      summary: Find games within a court
      description: Get all Games installed within a court.
      operationId: getCourtGames
      parameters:
        - name: courtId
          in: path
          description: Database ID for court.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/GamesResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
  /courts/{courtId}/switchGame:
    put:
      tags:
        - Courts
      summary: Switch Game
      description: Start a game or asset flip in the given court. 
      operationId: switchGame
      parameters:
        - name: courtId
          in: path
          description: The court ID
          required: true
          schema:
            type: string
      requestBody:
        description: Court Id
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/SwitchGameBody"
        required: true
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/GameSwitchResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
  /courts/{courtId}/getGameSessionResult/{gameResultId}:
    get:
      tags:
        - Courts
      summary: Get game session result
      description: Get the score result from a gameResultId
      operationId: getGameSessionResult
      parameters:
        - name: courtId
          in: path
          description: The court ID
          required: true
          schema:
            type: string
        - name: gameResultId
          in: path
          description: The game resultId
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/getGameSessionResultResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
  /courts/{courtId}/setPlayers:
    put:
      tags:
        - Courts
      summary: Set players in court
      description: Sets the players currently playing on a court.
      operationId: setPlayersOnClourt
      parameters:
        - name: courtId
          in: path
          description: The court ID
          required: true
          schema:
            type: string
      requestBody:
        description: Court Id
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/SetPlayerToCourtBody"
        required: true
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CourtStatusResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
      x-codegen-request-body-name: body
  /courts/{courtId}/setConfiguration:
    put:
      tags:
        - Courts
      summary: Set Game Configuration
      description: Set Game configuration on court
      operationId: setGameConfigurationOnCourt
      parameters:
        - name: courtId
          in: path
          description: The court ID
          required: true
          schema:
            type: string
      requestBody:
        description: Court Id
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/SetCourtConfigurationBody"
        required: true
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CourtStatusResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
      x-codegen-request-body-name: body
  /courts/{courtId}/setEndpoint:
    put:
      tags:
        - Courts
      summary: Set Court information push endpoint
      description: Set endpoint to where the game status and results will be delivered. All information pushes comes with a POST request from our servers
      operationId: setCourtEndpoint
      parameters:
        - name: courtId
          in: path
          description: The court ID
          required: true
          schema:
            type: string
      requestBody:
        description: Court Id
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/SetCourtEndpointBody"
        required: true
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/SetCourtEndpointResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
      x-codegen-request-body-name: body
  /courts/{courtId}/health:
    put:
      tags:
        - Courts
      summary: Get health status 
      description: Get the current health status of a court.
      parameters:
        - name: courtId
          in: path
          description: The court ID
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/HealthResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
      x-codegen-request-body-name: body
  /games/{gameId}:
    get:
      tags:
        - Games
      summary: Get Game info
      description: Get Game info
      operationId: getGame
      parameters:
        - name: gameId
          in: path
          description: The game ID
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/GameResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
  /games/{gameId}/start:
    put:
      tags:
        - Games
      summary: Start Game
      description: Start Game within a court.
      operationId: startGame
      parameters:
        - name: gameId
          in: path
          description: The game ID
          required: true
          schema:
            type: string
      requestBody:
        description: Court Id
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/StartGameBody"
        required: true
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/GameControlResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
      x-codegen-request-body-name: body
  /games/{gameId}/stop/:
    put:
      tags:
        - Games
      summary: Stop Game
      description: Stop Game started within court.
      operationId: stopGame
      parameters:
        - name: gameId
          in: path
          description: The game ID
          required: true
          schema:
            type: string
      requestBody:
        description: Court Id
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/StartGameBody"
        required: true
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/GameControlResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
      x-codegen-request-body-name: body
  /stats/{date}:
    get:
      tags:
        - Statistics
      summary: Get statistics for all courts
      description: Get overall statistics for all courts on a date
      parameters:
        - name: date
          in: path
          description: Date using mm-dd-yyyy format
          required: true
          schema:
            type: string
      requestBody:
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/ProductType"
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CourtsStatsResponse"
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
  /stats/{date}/{courtId}:
    get:
      tags:
        - Statistics
      summary: Get statistics for a court
      description: Get overall statistics for a specific court on a date
      parameters:
        - name: date
          in: path
          description: Date using mm-dd-yyyy format
          required: true
          schema:
            type: string
        - name: courtId
          in: path
          description: Database ID for court.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CourtStatsResponse"
              dateStart:
                type: string
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
  /stats/{dateStart}/{dateEnd}/overallBetweenDates:
    get:
      tags:
        - Statistics
      summary: Get statistics for all courts between dates
      description: Get statistics for all courts between dates
      parameters:
        - name: dateStart
          in: path
          description: Date using mm-dd-yyyy format
          required: true
          schema:
            type: string
        - name: dateEnd
          in: path
          description: Date using mm-dd-yyyy format
          required: true
          schema:
            type: string
      requestBody:
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/ProductType"
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CourtsStatsBetweenDatesResponse"
              dateStart:
                type: string
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
  /stats/{dateStart}/{dateEnd}/{courtId}/overallBetweenDatesCourtId:
    get:
      tags:
        - Statistics
      summary: Get statistics for a court between dates
      description: Get statistics for a court between dates
      parameters:
        - name: dateStart
          in: path
          description: Date using mm-dd-yyyy format
          required: true
          schema:
            type: string
        - name: dateEnd
          in: path
          description: Date using mm-dd-yyyy format
          required: true
          schema:
            type: string
        - name: courtId
          in: path
          description: Database ID for court.
          required: true
          schema:
            type: string
      responses:
        200:
          description: Success Response
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/CourtStatsBetweenDatesResponse"
              dateStart:
                type: string
        400:
          description: Bad Request
          content:
            "*/*":
              schema:
                $ref: "#/components/schemas/BadRequest"
  Game info callback:
    post:
      tags:
        - Callback events
      summary: Send court messages to a registered endpoint
      description: After registering a url using the Set Court information push endpoint method, our servers will start to post messages to your registered endpoint. Here is the type description of some messages that we send. (gameStatus - information if the game is running or paused) (gameResults - information related to game results)
      requestBody:
        description:
        content:
          "application/json":
            schema:
              $ref: "#/components/schemas/CallbackCourtMessage"
components:
  schemas:
    AcceptedResponse:
      type: object
      properties:
        status:
          type: number
        message:
          type: string
    BadRequest:
      type: object
      properties:
        status:
          type: number
          description: Error message
        error:
          type: string
    SetCourtConfigurationBody:
      type: object
      required:
        - gameId
        - values
      properties:
        gameId:
          type: string
          description: The Game Id
        values:
          type: object
          properties:
            duration:
              type: integer
              description: Duration of the game in seconds
            difficulty:
              type: number
              description: Difficulty of the game (a number between 0 and 1)
    DefaultResponse:
      type: object
      required:
        - status
        - message
      properties:
        status:
          type: string
        message:
          type: string
    ConfigurationResponse:
      type: object
      properties:
        duration:
          type: string
        difficulty:
          type: string
        status:
          type: string
    CourtStatusResponse:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        status:
          type: string
        description:
          type: string
        beaconId:
          type: string
        location:
          $ref: "#/components/schemas/location"
        game:
          $ref: "#/components/schemas/GameResponse"
        players:
          type: array
          items:
            $ref: "#/components/schemas/PlayerBody"
        configuration:
          $ref: "#/components/schemas/ConfigurationResponse"
    PlayerBody:
      required:
        - firstName
        - lastName
        - email
      type: object
      properties:
        firstName:
          type: string
          description: The first name of the user
        lastName:
          type: string
          description: The last name of the user
        email:
          type: string
          description: The email of the user
    SetPlayerToCourtBody:
      required:
        - matchId
        - players
      type: object
      properties:
        matchId:
          type: string
          description: The id of the match
        players:
          type: array
          items:
            $ref: "#/components/schemas/PlayerBody"
    SwitchGameBody:
      type: object
      properties:
        gameId:
          type: string
          description: Object id of the game that should be switched to. Available gameIds are found using the `/courts/{courtId}/games` endpoint.
        versionNumber:
          type: string
          description: The version number within the game (null sets to current version on court).
        flipId:
          type: string
          description: If a custom asset flip should be started, this specifies the id of the asset flip. If set, the gameId can be omitted. Available flipIds are found using the `/courts/{courtId}/games` endpoint.
    getGameSessionResultBody:
      required:
        - gameResultId
      type: object
      properties:
        gameResultId:
          type: string
          description: gameResultId from the switch game response
    StartGameBody:
      required:
        - courtId
      type: object
      properties:
        courtId:
          type: string
          description: Court Id
    GameVersionResponse:
      type: object
      required:
        - id
        - number
      properties:
        id:
          type: string
        number:
          type: string
    GameResponse:
      type: object
      required:
        - id
        - name
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        dispName:
          type: string
        versions:
          type: array of strings
        players:
          type: string
    GamesResponse:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          format: int32
        results:
          type: array
          items:
            $ref: "#/components/schemas/GameResponse"
    CourtResponse:
      type: object
      required:
        - id
        - title
      properties:
        id:
          type: integer
          format: int32
        title:
          type: string
        description:
          type: string
        beaconId:
          type: string
        location:
          $ref: "#/components/schemas/location"
    CourtsResponse:
      type: object
      required:
        - count
        - results
      properties:
        count:
          type: integer
          format: int32
        results:
          type: array
          items:
            $ref: "#/components/schemas/CourtResponse"
    GameSwitchResponse:
      type: object
      required:
        - gameId
        - versionNumber
        - message
      properties:
        gameId:
          type: string
        versionNumber:
          type: string
        message:
          type: string
    getGameSessionResultResponse:
      type: object
      required:
        - gameResultId
        - results
        - message
      properties:
        gameResultId:
          type: string
        results:
          type: array
        message:
          type: string
    GameControlResponse:
      type: object
      required:
        - gameId
        - courtId
        - message
      properties:
        gameId:
          type: string
        courtId:
          type: string
        message:
          type: string
    SetCourtEndpointBody:
      type: object
      required:
        - endpoint
      properties:
        endpoint:
          type: string
    SetCourtEndpointResponse:
      type: object
      required:
        - courtId
        - message
      properties:
        courtId:
          type: string
        message:
          type: string
    HealthResponse:
      type: object
      properties:
        courtId:
          type: string
        health:
          type: object
          properties:
            hasActiveSubscription:
              type: boolean 
            displayConnected:
              type: boolean
            hasSensorIssue:
              type: boolean
            updateStatus:
              type: string
            onlineStatus:
              type: string
    CallbackCourtMessage:
      type: object
      properties:
        method:
          description: The type of message. eg. gameStatus, gameResults
          type: string
        data:
          description: The information related to the method
          type: object
    location:
      type: object
      required:
        - longitude
        - latitude
      properties:
        longitude:
          type: integer
          format: int32
        latitude:
          type: integer
          format: int32
    GameStats:
      type: object
      properties:
        totalHours:
          description: Total hours played on a game
          type: integer
        gameId:
          type: string
    CourtStats:
      type: object
      properties:
        totalHours:
          type: integer
        courtId:
          type: string
        games:
          description: Distribution of played hours among games
          type: array
          items:
            $ref: "#/components/schemas/GameStats"
    ProductType:
      type: object
      properties:
        productType:
          type: string
          description: A product type between 'squash' or 'multiball'
    CourtsStatsResponse:
      type: object
      properties:
        date:
          type: date
        totalHours:
          description: Total hours played on a time interval
          type: number
        courts:
          type: array
          items:
            $ref: "#/components/schemas/CourtStats"
    CourtsStatsBetweenDatesResponse:
      type: object
      properties:
        dateStart:
          type: date
        dateEnd:
          type: date
        totalHours:
          description: Total hours played on a time interval
          type: number
        courts:
          type: array
          items:
            $ref: "#/components/schemas/CourtStats"
    CourtStatsResponse:
      type: object
      properties:
        date:
          type: date
        totalHours:
          description: Total hours played on a time interval
          type: number
        courtId:
          type: string
        games:
          type: array
          description: Distribution of played hours among games
          items:
            $ref: "#/components/schemas/GameStats"
    CourtStatsBetweenDatesResponse:
      type: object
      properties:
        dateStart:
          type: date
        dateEnd:
          type: date
        totalHours:
          description: Total hours played on a time interval
          type: number
        courtId:
          type: string
        games:
          type: array
          description: Distribution of played hours among games
          items:
            $ref: "#/components/schemas/GameStats"
  securitySchemes:
    basicAuth: # <-- arbitrary name for the security scheme
      type: http
      scheme: basic