NAV
shell http

# Introduction

This documents an HTTP based API for basic control of ProScoreboard.

# Requests

## Scheme

Requests may be made over HTTP or HTTPS depending on your network settings in ProScoreboard.

## Prefix

All request paths are prefixed with `/api/0` in addition to the standard URL components for the scheme (https), host, and port.

For an end point with the path `/data/data`, the full request would be:

`GET https://localhost:8080/api/0/data/data`

The address "localhost" and port number "8080" is used for examples, your address will depend on your network settings and your port number is configured in ProScoreboard preferences.

## Authentication

> API Access Request:

    // HTTP
    GET /api/0/data/playlists HTTP/1.1
    Host: localhost:8080
    Content-Type: application/json

    // HTTPS
    GET /api/0/data/playlists HTTP/1.1
    Host: localhost:8080
    Content-Type: application/json
    Authorization: Bearer <your unique key here>

    // HTTPS
    curl -H "Authorization: Bearer <your unique key here>" -X GET https://localhost:8080/api/0/data/scores -k

Access to the API is controlled via API keys. Keys can be managed in ProScoreboard preferences.

The API expects the API key to be passed with all requests via an Authorization header like the following:

`Authorization: Bearer <your unique key here>`

You must replace `<your unique key here>` with your personal API key.

## JSON

    POST /api/0/opacity/layer/0 HTTP/1.1
    Host: localhost:8080
    Content-Type: application/json

    { "value": 0.5 }

Some POST requests can take JSON data as a parameter; these are noted by the sections in the documentation that contain a 'Request Body'. Our API conforms to the JSON 1.0 Specification

### HTTP

If JSON is needed for an HTTP request, the folowing should be included in the request:

`{ "<requestBodyKey>": <requestBodyValue> }`

- NOTE: The above is only an example. Some requests will have more keys/values, but these will be defined in the request body sections of the documentation.

### CURL

If JSON is needed for a cURL request, the following should be included in the request:

`-d '{ "<requestBodyKey>":<requestBodyValue> }' -H "Content-Type: application/json"`

- NOTE: The correct "requestBodyKey" and "requestBodyValue" can be found in the Request Body section of each request that should/can include JSON.

# Data

Each sport contains its own scoring properties. Custom sports will be user defined.

## Scores

> Example Request:

    GET /api/0/data/scores HTTP/1.1
    Host: localhost:8080
    Content-Type: application/json

    curl -X GET http://localhost:8080/api/0/data/scores -k

Each return value contians a UUID, sportMode and Version number...

`"uuid" : "<unique identifier>"`,

`"version" : "1.0"`,

`"sportMode" : "<sport name>"`

Along with the following properties that define each sport:

> JSON response:

## Australian Football

    {
      "sportMode" : "AustralianFootball",
      "quarter" : "1",
      "sportMode" : "Custom",
      "team1Behinds" : "2",
      "team1Goals" : "3",
      "team1Name" : "Atlanta",
      "team1Score" : "20",
      "team2Behinds" : "3",
      "team2Goals" : "4",
      "team2Name" : "Boston",
      "team2Score" : "27"
    }

- quarter
- team1Behinds
- team1Goals
- team1Name
- team1Score
- team2Behinds
- team2Goals
- team2Name
- team2Score

## Baseball

    {
      "sportMode" : "Baseball",
      "balls" : "1",
      "errors" : "1",
      "hits" : "5",
      "inning" : "5",
      "outs" : "0",
      "period" : "1",
      "possession" : 1,
      "runs" : "2",
      "strikes" : "0"
      "topBottom" : "T"
      "teamOneRuns" : "3"
      "teamOneErrors" : "2"
      "teamOneHits" : "4"
      "teamOneLineScore1" : "0"
      "teamOneLineScore2" : "0"
      "teamOneLineScore3" : "3"
      "teamOneLineScore4" : ""
      "teamOneLineScore5" : ""
      "teamOneLineScore6" : ""
      "teamOneLineScore7" : ""
      "teamOneLineScore8" : ""
      "teamOneLineScore9" : ""
      "teamTwoRuns" : "4"
      "teamTwoErrors" : "0"
      "teamTwoHits" : "3"
      "teamTwoLineScore1" : "0"
      "teamTwoLineScore2" : "2"
      "teamTwoLineScore3" : "2"
      "teamTwoLineScore4" : ""
      "teamTwoLineScore5" : ""
      "teamTwoLineScore6" : ""
      "teamTwoLineScore7" : ""
      "teamTwoLineScore8" : ""
      "teamTwoLineScore9" : ""
    }

- balls
- errors
- hits
- inning
- outs
- possession
- runs
- strikes
- topBottom ("T" or "B")
- teamOneRuns
- teamOneErrors
- teamOneHits
- teamOneLineScore1
- teamOneLineScore2
- teamOneLineScore3
- teamOneLineScore4
- teamOneLineScore5
- teamOneLineScore6
- teamOneLineScore7
- teamOneLineScore8
- teamOneLineScore9
- teamTwoRuns
- teamTwoErrors
- teamTwoHits
- teamTwoLineScore1
- teamTwoLineScore2
- teamTwoLineScore3
- teamTwoLineScore4
- teamTwoLineScore5
- teamTwoLineScore6
- teamTwoLineScore7
- teamTwoLineScore8
- teamTwoLineScore9

## Basketball

    {
      "sportMode" : "Basketball",
      "period" : "2",
      "possession" : 0,
      "sportMode" : "Basketball",
      "team1Bonus1" : false,
      "team1Bonus2" : false,
      "team1Fouls" : "4",
      "team1Score" : "6",
      "team1TimeOuts" : "3",
      "team2Bonus1" : true,
      "team2Bonus2" : true,
      "team2Fouls" : "0",
      "team2Score" : "0",
      "team2TimeOuts" : "3"
    }

- period
- possession
- team1Bonus1
- team1Bonus2
- team1Fouls
- team1Score
- team1TimeOuts
- team2Bonus1
- team2Bonus2
- team2Fouls
- team2Score
- team2TimeOuts

## Football

    {
      "sportMode" : "Football",
      "ballLocation" : "33",
      "down" : "3",
      "period" : "3",
      "possession" : 1,
      "team1Score" : "24",
      "team1TimeOuts" : "2",
      "team2Score" : "12",
      "team2TimeOuts" : "1",
      "toGo" : "7"
    }

- ballLocation
- down
- period
- possession
- team1Score
- team1TimeOuts
- team2Score
- team2TimeOuts
- toGo

## Hockey

    {
      "sportMode" : "Hockey",
      "period" : "2",
      "team1Saves" : "5",
      "team1Score" : "2",
      "team1Shots" : "2",
      "team1TimeOuts" : "3",
      "team2Saves" : "2",
      "team2Score" : "1",
      "team2Shots" : "3",
      "team2TimeOuts" : "3"
    }

- period
- team1Saves
- team1Score
- team1Shots
- team1TimeOuts
- team2Saves
- team2Score
- team2Shots
- team2TimeOuts

## Lacrosse

    {
      "sportMode" : "Lacrosse",
      "period" : "2",
      "possession" : 0,
      "team1Saves" : "5",
      "team1Score" : "2",
      "team1Shots" : "2",
      "team1TimeOuts" : "3",
      "team2Saves" : "2",
      "team2Score" : "1",
      "team2Shots" : "3",
      "team2TimeOuts" : "3"
    }

- period
- possession
- team1Saves
- team1Score
- team1Shots
- team1TimeOuts
- team2Saves
- team2Score
- team2Shots
- team2TimeOuts

## Soccer

    {
      "sportMode" : "Soccer",
      "extraTime" : "3",
      "period" : "2",
      "team1Corner" : "5",
      "team1Saves" : "1",
      "team1Score" : "4",
      "team1Shots" : "3",
      "team1TimeOuts" : "3",
      "team2Corner" : "1",
      "team2Saves" : "0",
      "team2Score" : "1",
      "team2Shots" : "0",
      "team2TimeOuts" : "3"
    }

- extraTime
- period
- team1Corner
- team1Saves
- team1Score
- team1Shots
- team1TimeOuts
- team2Corner
- team2Saves
- team2Score
- team2Shots
- team2TimeOuts

## Tennis

    {
      "sportMode" : "Tennis",
      "currentSet" : 4,
      "period" : "4",
      "possession" : 1,
      "team1Games" : "0",
      "team1Score" : "0",
      "team1Set1" : "2",
      "team1Set2" : "1",
      "team1Set3" : "4",
      "team1Set4" : "0",
      "team1Set5" : " ",
      "team1Set6" : " ",
      "team1Set7" : " ",
      "team1Set8" : " ",
      "team1Set9" : " ",
      "team1Sets" : "2",
      "team1TimeOuts" : "1",
      "team2Games" : "0",
      "team2Score" : "0",
      "team2Set1" : "4",
      "team2Set2" : "0",
      "team2Set3" : "0",
      "team2Set4" : "0",
      "team2Set5" : " ",
      "team2Set6" : " ",
      "team2Set7" : " ",
      "team2Set8" : " ",
      "team2Set9" : " ",
      "team2Sets" : "1",
      "team2TimeOuts" : "3"
    }

- currentSet
- period
- possession
- team1Games
- team1Score
- team1Set1
- team1Set2
- team1Set3
- team1Set4
- team1Set5
- team1Set6
- team1Set7
- team1Set8
- team1Set9
- team1Sets
- team1TimeOuts
- team2Games
- team2Score
- team2Set1
- team2Set2
- team2Set3
- team2Set4
- team2Set5
- team2Set6
- team2Set7
- team2Set8
- team2Set9
- team2Sets
- team2TimeOuts

## Volleyball

    {
      "sportMode" : "Volleyball",
      "currentSet" : 4,
      "period" : "4",
      "possession" : 0,
      "sportMode" : "Volleyball",
      "team1Games" : "2",
      "team1Score" : "0",
      "team1Set1" : "24",
      "team1Set2" : "24",
      "team1Set3" : "21",
      "team1Set4" : "0",
      "team1Set5" : "0",
      "team1Set6" : " ",
      "team1Set7" : " ",
      "team1Set8" : " ",
      "team1Set9" : " ",
      "team1TimeOuts" : "0",
      "team2Games" : "1",
      "team2Score" : "0",
      "team2Set1" : "18",
      "team2Set2" : "21",
      "team2Set3" : "24",
      "team2Set4" : "0",
      "team2Set5" : "0",
      "team2Set6" : " ",
      "team2Set7" : " ",
      "team2Set8" : " ",
      "team2Set9" : " ",
      "team2TimeOuts" : "0"
    }

- currentSet
- possession
- team1Games
- team1Score
- team1Set1
- team1Set2
- team1Set3
- team1Set4
- team1Set5
- team1Set6
- team1Set7
- team1Set8
- team1Set9
- team1TimeOuts
- team2Games
- team2Score
- team2Set1
- team2Set2
- team2Set3
- team2Set4
- team2Set5
- team2Set6
- team2Set7
- team2Set8
- team2Set9
- team2TimeOuts

## Custom

    {
      "sportMode" : "Custom",
      "game1" : {
        "possession" : "0",
        "quarter" : "1",
        "team1Goals" : "5",
        "team1Name" : "Atlanta",
        "team1Saves" : "0",
        "team1TimeOuts" : "0",
        "team2Goals" : "1",
        "team2Name" : "Boston",
        "team2Saves" : "0",
        "team2TimeOuts" : "0"
      },
      "game2" : {
        "possession" : "0",
        "quarter" : "1",
        "team1Goals" : "1",
        "team1Name" : "Team 3",
        "team1Saves" : "0",
        "team1TimeOuts" : "0",
        "team2Goals" : "4",
        "team2Name" : "Team 4",
        "team2Saves" : "0",
        "team2TimeOuts" : "0"
      }
    }

In the case of `Custom`, the score properties are defined by the user. In this example, the score properties are:

`Goals`, `Saves`, `Time Outs`

- NOTE: If `isGrouped` is selected in the Custom Settings and there is more then one grouping, the score properties will be placed in a sub-array of game values where the key of each game = `game` + `<ordered number>`

Keys are derived from the `Team Index` and `Title` of each `ScoreObject` output in CamelCase (e.g. team1TimeOuts)

# Errors

The API uses the following error codes:

Error Code | Meaning
--- | ---
400 | Bad Request -- Your request was invalid.
401 | Unauthorized -- Authorization failed.
403 | Forbidden -- The endpoint requested is hidden for administrators only.
404 | Not Found -- The specified endpoint could not be found.
405 | Method Not Allowed -- You tried to access an endpoint with an invalid method.
500 | Internal Server Error -- We had a problem with our server. Try again later.
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

shell http