6. Tournament API Overview

GET: /api/v1/tournament/match

This URL retrieves a list of all the matches. You may specify extra search parameters to retrieve speciﬁc types of matches.

Parameters:

includePresetData - boolean (Optional)
type - Enumerator ['all', 'due', 'active', 'joinable', 'finished'] (Optional)
perPage - Integer (Optional) page - Integer (Optional) gameId - Mixed (Optional) from - Date (Optional)
to - Date (Optional)
opid - String (Optional)

Specifying a to and from date will allow you to retrieve matches between the specified range.

Throws:

HttpNotFoundException

Example response:

{
    "data": [
        {
        "id": 1,
        "presetId": 1,
        "startingTime": "2018-04-10 12:30:00",
        "endingTime": "2018-04-10 12:40:00",
        "joinable": false,
        "deleted_at": null,
        "created_at": "2018-04-10 12:24:59",
        "updated_at": "2018-04-10 12:24:59",
        "quitable": false
        }
    ],
    "meta": {
        "page": 1,
        "perPage": 15,
        "total": 1
    }
}

Example response with "includePresetData" parameter:

{
    "data": [
        {
            "id": 1,
            "startingTime": "2018-04-10 12:30:00",
            "endingTime": "2018-04-10 12:40:00",
            "joinable": false,
            "deleted_at": null,
            "created_at": "2018-04-10 12:24:59",
            "updated_at": "2018-04-10 12:24:59",
            "quitable": false,
            "preset": {
                "id": 1,
                "presetName": "test",
                "matchName": "test",
                "matchDuration": "600",
                "entryFee": 2500,
                "playerDuration": "600",
                "playerStartingBalance": 2500,
                "allowRebuy": true,
                "resetBalanceOnRebuy": true,
                "bonusOnlyRewards": false,
                "prizes": [
                    1250,
                    750,
                    250
                ],
                "prizeType": "PROPORTIONAL",
                "gameId": 1075,
                "created_at": "2018-04-10 12:24:50",
                "updated_at": "2018-04-10 12:24:50",
                "proportionalPrizeValues": [
                    "50",
                    "30",
                    "10"
                ]
            }
        }
    ],
    "meta": {
        "page": 1,
        "perPage": 15,
        "total": 1
    }
}

GET: /api/v1/tournament/match/{matchId}

This URL retrieves information on a single match. You may specify an extra parameter to include additional match information.

Parameters:

includePresetData - boolean (Optional)

Throws:

HttpNotFoundException

Example response:

{
    "data": {
        "id": 1,
        "presetId": 1,
        "startingTime": "2018-04-10 12:30:00",
        "endingTime": "2018-04-10 12:40:00",
        "joinable": false, 
        "deleted_at": null,
        "created_at": "2018-04-10 12:24:59",
        "updated_at": "2018-04-10 12:24:59",
        "quitable": false
    },
    "meta": [
    ]
}

Example response with "includePresetData" parameter:

{
    "data": {
        "id": 1,
        "startingTime": "2018-04-10 12:30:00",
        "endingTime": "2018-04-10 12:40:00",
        "joinable": false, 
        "deleted_at": null,
        "created_at": "2018-04-10 12:24:59",
        "updated_at": "2018-04-10 12:24:59",
        "quitable": false, 
        "preset": {
            "id": 1,
            "presetName": "test", 
            "matchName": "test", 
            "matchDuration": "600",
            "entryFee": 2500,
            "playerDuration": "600",
            "playerStartingBalance": 2500, 
            "allowRebuy": true, 
            "resetBalanceOnRebuy": true, 
            "bonusOnlyRewards": false, 
            "prizes": [
                1250,
                750,
                250
            ],
            "prizeType": "PROPORTIONAL",
            "gameId": 1075,
            "created_at": "2018-04-10 12:24:50",
            "updated_at": "2018-04-10 12:24:50",
            "proportionalPrizeValues": [ 
                "50",
                "30",
                "10"
            ]
        }
    },
    "meta": [
    ]
}

POST: /api/v1/tournament/match/{matchId}/player/{playerId}/join

This URL allows you to the add a specific player to a specific match given that the match is still in a joinable state. You can optionally pass a nameTag parameter to this endpoint in order to specify a custom name tag for the specified player. If one isn't provided then a random one will be chosen. You may not change name tags after a player has joined.

An actualPaid parameter should be passed confirming how much the player paid to join the match in the server's configured base currency. This should include the actual amount after any conversion rates have been applied.

NOTE: This API call itself does not deduct money from the player's account.

Parameters:

nameTag - (Optional) String
entryType - (Optional) Enum ('PAID' [default], 'FREE')
actualPaid - (Required if entryType is 'PAID') Integer (If not speciﬁed, the preset's default entry fee will be used)

Throws:

HttpBadRequestException
HttpNotFoundException
TournamentJoinException

Example response:

{
    "data": {
        "id": 1,
        "matchId": 1,
        "playerId": 1,
        "balance": 2500,
        "tiebreakerScore": 0, 
        "nameTag": "kieron",
        "entryType": "PAID", 
        "actualPaid": 0,
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18"
    },
    "meta": [
    ]
}

POST: /api/v1/tournament/match/{matchId}/player/{playerId}/quit

This URL allows you to remove a specific player from a specific match given that the match has not yet started.

Throws:

HttpNotFoundException
TournamentQuitException

Example response:

{
    "data": [
    ],
    "meta": [
    ]
}

POST: /api/v1/tournament/match/{matchId}/player/{playerId}/rebuy

This URL allows you to the re-add a specific player to a specific match given that the match is still in a joinable state. This will reuse the player's old nameTag. This should only be called after the player has initially joined.

An actualPaid parameter should be passed confirming how much the player paid to re-join the match in the server's configured base currency. This should include the actual amount after any conversion rates have been applied.

NOTE: This API call itself does not deduct money from the player's account.

Parameters:

entryType - (Optional) Enum ('PAID' [default], 'FREE')
actualPaid - (Required if entryType is 'PAID') Integer (If not speciﬁed, the preset's default entry fee will be used)

Throws:

HttpBadRequestException
HttpNotFoundException
TournamentJoinException

Example response:

{
    "data": {
        "id": 1,
        "matchId": 1,
        "playerId": 1,
        "balance": 2500,
        "tiebreakerScore": 0, 
        "nameTag": "kieron",
        "entryType": "PAID", 
        "actualPaid": 0,
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18"
    },
    "meta": [
    ]
}

GET: /api/v1/tournament/match/{matchId}/player/{playerId}/entry

This URL allows you to retrieve a specific player's profile.

Parameters:

foreign - (Optional) any (This will refer to the foreign player identifier. In this case it is the operator.
eventFilter[] - (Optional) Enum ('JOIN', 'FREE_JOIN', 'QUIT', 'REBUY', 'FREE_REBUY', 'SET_BALANCE', 'TAKE_BALANCE', 'ADD_BALANCE')

Throws:

HttpNotFoundException
TournamentEntryException

Example response:

{
    "data": {
        "id": 1,
        "matchId": 1,
        "playerId": 1,
        "balance": 2500,
        "tiebreakerScore": 0, 
        "nameTag": "kieron",
        "entryType": "PAID", "actualPaid": 0,
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18",
        "totalRebuys": 0, 
        "events": [
            {
              "eventType": "JOIN", 
              "meta": {
                "nameTag": "kieron",
                "entryType": "PAID", "actualPaid": 1500
              },
              "timestamp": "2019-02-28 08:15:46"
            },
            {
              "eventType": "TAKE_BALANCE", 
              "meta": {
                "oldBalance": 2500,
                "newBalance": 0
              },
              "timestamp": "2019-02-28 08:16:04"
            },
            {
              "eventType": "ADD_BALANCE", 
              "meta": {
                "oldBalance": 0,
                "newBalance": 1000
                },
              "timestamp": "2019-02-28 08:16:12"
            },
            {
              "eventType": "TAKE_BALANCE", 
              "meta": {
                "oldBalance": 1000,
                "newBalance": 0
              },
              "timestamp": "2019-02-28 08:16:34"
            },
            {
              "eventType": "REBUY", 
              "meta": {
                "entryType": "PAID", 
                "actualPaid": 1500
              },
              "timestamp": "2019-02-28 08:16:56"
            }
        ]
    },
    "meta": [
    ]
}

POST: /api/v1/tournament/match/{matchId}/player/{playerId}/setbalance

This URL allows you to set the balance of a specific player on a specific match. This endpoint requires an additional balance parameter of which will be the new balance of the specified player.

Parameters:

balance - Integer

Throws:

HttpBadRequestException
HttpNotFoundException
TournamentBalanceException

Example response:

{
    "data": {
        "id": 1,
        "matchId": 1,
        "playerId": 1,
        "balance": 2500,
        "tieBreakerScore": 0, 
        "nameTag": "kieron",
        "entryType": "PAID", 
        "actualPaid": 0,
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18"
    },
    "meta": [
    ]
}

POST: /api/v1/tournament/match/{matchId}/player/{playerId}/addbalance

This URL allows you to add the specified value to the player's current balance. This endpoint requires an additional value parameter which will be added to the player's balance.

Parameters:

value - Integer

Throws:

HttpBadRequestException
HttpNotFoundException
TournamentBalanceException

Example response:

{
    "data": {
        "id": 1,
        "matchId": 1,
        "playerId": 1,
        "balance": 2500,
        "tiebreakerScore": 0, 
        "nameTag": "kieron",
        "entryType": "PAID", 
        "actualPaid": 0,
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18"
    },
    "meta": [
    ]
}

POST: /api/v1/tournament/match/{matchId}/player/{playerId}/takebalance

This URL allows you to take a specified value from the player's current balance. This endpoint requires an additional value parameter of which will be removed from the player's balance.

Parameters:

value - Integer

Throws:

HttpBadRequestException
HttpNotFoundException
TournamentBalanceException

Example response:

{
    "data": {
        "id": 1,
        "matchId": 1,
        "playerId": 1,
        "balance": 2500,
        "tiebreakerScore": 0, 
        "nameTag": "kieron",
        "entryType": "PAID", 
        "actualPaid": 0,
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18"
    },
    "meta": [
    ]
}

POST: /api/v1/tournament/match/{matchId}/player/{playerId}/set-tiebreaker-score

This URL allows you to set the tiebreaker score of a specific player.

Parameters:

score - Integer

Throws:

HttpBadRequestException
HttpNotFoundException
TournamentTieBreakerScoreException

Example response:

{
    "data": {
        "id": 1,
        "matchId": 1,
        "playerId": 1,
        "balance": 2500,
        "tiebreakerScore": 100, 
        "nameTag": "kieron",
        "entryType": "PAID", 
        "actualPaid": 0,
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18"
    },
    "meta": [
    ]
}

POST: /api/v1/tournament/match/{matchId}/player/{playerId}/add-tiebreaker-score

This URL allows you to add a tiebreaker score to a specific player.

Parameters:

score - Integer

Throws:

HttpBadRequestException
HttpNotFoundException
TournamentTieBreakerScoreException

Example response:

{
    "data": {
        "id": 1,
        "matchId": 1,
        "playerId": 1,
        "balance": 2500,
        "tiebreakerScore": 100, 
        "nameTag": "kieron",
        "entryType": "PAID", 
        "actualPaid": 0,
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18"
    },
    "meta": [
    ]
}

POST: /api/v1/tournament/match/{matchId}/player/{playerId}/take-tiebreaker-score

This URL allows you to take a tiebreaker score from a specific player.

Parameters:

score - Integer

Throws:

HttpBadRequestException
HttpNotFoundException
TournamentTieBreakerScoreException

Example response:

{
    "data": {
        "id": 1,
        "matchId": 1,
        "playerId": 1,
        "balance": 2500,
        "tiebreakerScore": 0, 
        "nameTag": "kieron",
        "entryType": "PAID", 
        "actualPaid": 0,
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18"
    },
    "meta": [
    ]
}

GET: /api/v1/tournament/player/{player}/matches

This URL retrieves a list of all of the matches that a specific player has joined. You may specify extra search parameters to retrieve specific types of matches.

Parameters:

type - Enumerator ['all', 'due', 'active', 'joinable', 'ﬁnished'] (Optional)
perPage - Integer (Optional) page - Integer (Optional) gameId - Mixed (Optional)

Throws:

HttpNotFoundException

Example response:

{
    "data": [
        {
            "nameTag": "kieron", 
            "match": {
                "id": 1,
                "presetId": 1,
                "startingTime": "2018-04-10 12:30:00",
                "endingTime": "2018-04-10 12:40:00",
                "joinable": false, 
                "deleted_at": null,
                "created_at": "2018-04-10 12:24:59",
                "updated_at": "2018-04-10 12:24:59",
                "quitable": false
            }
        }
    ],
    "meta": {
        "page": 1,
        "perPage": 15,
        "total": 1
    }
}

API ENDPOINTS (Do not require API key)

GET: /api/v1/tournament/match/{matchId}/leaderboard

This URL will return the entire leaderboard for the specified match in a paginated response.

Parameters:

perPage - Integer (Optional)
page - Integer (Optional)

Throws:

HttpBadRequestException
HttpNotFoundException
TournamentLeaderboardException

Example response:

{
    "data": [
        {
        "rank": 1,
        "balance": 2500, 
        "nameTag": "kieron",
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18"
        }
    ],
    "meta": [
        "page": 1,
        "perPage": 15,
        "total": 1
    ]
}

GET: /api/v1/tournament/match/{matchId}/leaderboard/me/{nameTag}

This URL will return the leaderboard section for the specified match for a specific player. Using the unique nameTag parameter to prevent people gathering insight into internal logic.

Parameters:

nameTag - String

Throws:

HttpBadRequestException
HttpNotFoundException
TournamentLeaderboardException

Example response:

{
    "data": {
        "rank": 1,
        "balance": 2500, 
        "nameTag": "kieron",
        "updated_at": "2018-04-17 13:08:18",
        "created_at": "2018-04-17 13:08:18"
    },
    "meta": [
    ]
}

API EXCEPTIONS

TournamentJoinException

Causes:

NO_LONGER_JOINABLE is thrown when the match joining period is over
PLAYER_NOT_FOUND is thrown if the specified player could not be found MATCH_NOT_FOUND is thrown if the specified match could not be found ALREADY_JOINED is thrown if the player has already joined NAMETAG_TAKEN is thrown if the specified name tag is already in use UNKNOWN_ERROR is thrown if something else goes wrong

Example response:

{
  "error": {
    "type": "TournamentJoinException",
    "message": "Unable to join the specified tournament match",
    "request": {
      "parameters": {
        "apiKey": "28b9f1bedba296cb1138232b49f9a61faecaee6c418d78f376d84a1119058384",
        "...": "..."
      }
    },
    "context": {
      "id": "...",
      "cause": "ALREADY_JOINED",
      "meta": {
        "match": {
          "id": 1,
          "presetId": 1,
          "startingTime": "2018-04-10 12:30:00",
          "endingTime": "2018-04-10 12:40:00",
          "joinable": false,
          "deleted_at": null,
          "created_at": "2018-04-10 12:24:59",
          "updated_at": "2018-04-10 12:24:59",
          "quitable": false
        },
        "entry": {
          "id": 1,
          "matchId": 1,
          "playerId": 1,
          "balance": 2500,
          "tiebreakerScore": 0,
          "nameTag": "kieron",
          "updated_at": "2018-04-17 13:08:18",
          "created_at": "2018-04-17 13:08:18"
        }
      }
    }
  }
}

TournamentQuitException

Causes:

PLAYER_NOT_FOUND is thrown if the specified player could not be found MATCH_NOT_FOUND is thrown if the specified match could not be found NOT_IN_TOURNAMENT is thrown if the player hasn't joined the specified match UNKNOWN_ERROR is thrown if something else goes wrong

Example response:

{
  "error": {
    "type": "TournamentQuitException",
    "message": "Unable to quit the specified tournament match", 
    "request": {
      "parameters": { 
        "apiKey":"28b9f1bedba296cb1138232b49f9a61faecaee6c418d78f376d84a1119058384", 
        "...": "..."
      }
    },
    "context": { 
      "id": "...",
      "cause": "NOT_IN_TOURNAMENT",
      "meta": {
        "match": {
          "id": 1,
          "presetId": 1,
          "startingTime": "2018-04-10 12:30:00",
          "endingTime": "2018-04-10 12:40:00",
          "joinable": false, 
          "deleted_at": null,
          "created_at": "2018-04-10 12:24:59",
          "updated_at": "2018-04-10 12:24:59",
          "quitable": false
        }
      }
    }
  }
}

TournamentEntryException

Causes:

PLAYER_NOT_FOUND is thrown if the specified player could not be found MATCH_NOT_FOUND is thrown if the specified match could not be found NOT_IN_TOURNAMENT is thrown if the player hasn't joined the specified match UNKNOWN_ERROR is thrown if something else goes wrong

Example response:

{
    "error": {
        "type": "TournamentEntryException",
        "message": "Unable to find the specified player entry", 
        "request": {
          "parameters": { 
            "apiKey":"28b9f1bedba296cb1138232b49f9a61faecaee6c418d78f376d84a1119058384", 
            "...": "..."
          }
        },
        "context": { 
            "id": "...",
            "cause": "NOT_IN_TOURNAMENT",
            "meta": {
                "match": {
                    "id": 1,
                    "presetId": 1,
                    "startingTime": "2018-04-10 12:30:00",
                    "endingTime": "2018-04-10 12:40:00",
                    "joinable": false, 
                    "deleted_at": null,
                    "created_at": "2018-04-10 12:24:59",
                    "updated_at": "2018-04-10 12:24:59",
                    "quitable": false
                }
            }
        }
    }
}

TournamentBalanceException

Causes:

PLAYER_NOT_FOUND is thrown if the specified player could not be found MATCH_NOT_FOUND is thrown if the specified match could not be found NOT_IN_TOURNAMENT is thrown if the player hasn't joined the specified match UNKNOWN_ERROR is thrown if something else goes wrong
NOT_ENOUGH_BALANCE is thrown if the specified value is greater than the player's current balance INVALID_VALUE_SPECIFIED is thrown if the specified value does not match the parameter's requirements

Example response:

{
    "error": {
        "type": "TournamentBalanceException",
        "message": "Unable to modify the player's balance", 
        "request": {
            "parameters": { 
              "apiKey":"28b9f1bedba296cb1138232b49f9a61faecaee6c418d78f376d84a1119058384", 
              "...": "..."
            }
        },
        "context": { 
            "id": "...",
            "cause": "INVALID_VALUE_SPECIFIED",
            "meta": {
                "match": {
                    "id": 1,
                    "presetId": 1,
                    "startingTime": "2018-04-10 12:30:00",
                    "endingTime": "2018-04-10 12:40:00",
                    "joinable": false, 
                    "deleted_at": null,
                    "created_at": "2018-04-10 12:24:59",
                    "updated_at": "2018-04-10 12:24:59",
                    "quitable": false
                }
            }
        }
    }
}

TournamentTieBreakerScoreException

Causes:

PLAYER_NOT_FOUND is thrown if the specified player could not be found MATCH_NOT_FOUND is thrown if the specified match could not be found UNKNOWN_ERROR is thrown if something else goes wrong NOT_IN_TOURNAMENT is thrown if the player hasn't joined the specified match
INVALID_SCORE_SPECIFIED is thrown if the specified score does not match the parameter's requirements

Example response:

{
    "error": {
        "type": "TournamentTieBreakerScoreException",
        "message": "Unable to modify the player's tie-breaking score", 
        "request": {
            "parameters": { 
                "apiKey":"28b9f1bedba296cb1138232b49f9a61faecaee6c418d78f376d84a1119058384", 
                "...": "..."
            }
        },
        "context": { 
            "id": "...",
            "cause": "UNKNOWN_ERROR",
            "meta": {
                "match": {
                    "id": 1,
                    "presetId": 1,
                    "startingTime": "2018-04-10 12:30:00",
                    "endingTime": "2018-04-10 12:40:00",
                    "joinable": false, 
                    "deleted_at": null,
                    "created_at": "2018-04-10 12:24:59",
                    "updated_at": "2018-04-10 12:24:59",
                    "quitable": false
                },
                "entry": {
                    "id": 1,
                    "matchId": 1,
                    "playerId": 1,
                    "balance": 2500,
                    "tiebreakerScore": 0, 
                    "nameTag": "kieron",
                    "updated_at": "2018-04-17 13:08:18",
                    "created_at": "2018-04-17 13:08:18"
                }
            }
        }
    }
}

TournamentLeaderboardException

Causes:

NAMETAG_NOT_FOUND is thrown if the specified player could not be found MATCH_NOT_FOUND is thrown if the specified match could not be found UNKNOWN_ERROR is thrown if something else goes wrong

Example response:

{
    "error": {
        "type": "TournamentLeaderboardException",
        "message": "There was an issue with the specified request", 
        "request": {
            "parameters": { 
                "apiKey":"28b9f1bedba296cb1138232b49f9a61faecaee6c418d78f376d84a1119058384", 
                "...": "..."
            }
        },
        "context": { 
            "id": "...",
            "cause": "NAMETAG_NOT_FOUND",
            "meta": {
                "match": {
                    "id": 1,
                    "presetId": 1,
                    "startingTime": "2018-04-10 12:30:00",
                    "endingTime": "2018-04-10 12:40:00",
                    "joinable": false,
                    "deleted_at": null,
                    "created_at": "2018-04-10 12:24:59",
                    "updated_at": "2018-04-10 12:24:59",
                    "quitable": false
                }
            }
        }
    }
}