Reporting game finish

After the teams have played and the game server has the results, a request must be made to the OkLetsPlay back-end as follows. The game should implement proper retry mechanisms.

Synchronous games

In this scenario, the game should expect to send only a single result containing all participants' and teams' scores. The endpoint is idempotent to allow for retries, however only the first accepted result will be deemed valid.

Request example

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ${XXX-secret-jwt}' \
  -d '{
    "match_id": "600f36a861246f889d381029",
    "participants": [
      {
        "id": "user_id_1",
        "score": 300
      },
      {
        "id": "user_id_2",
        "score": 100
      }
    ],
    "teams": [
      {
        "id": "team_id_1",
        "score": 300,
        "ranking": 1
      },
      {
        "id": "team_id_2",
        "score": 100,
        "ranking": 2
      }
    ]
  }' \
  ${config.okletsplay_url}/api/game/v1/finish

• match_idstringThe unique id for this match.
• participantsarrayList of participants in the match.
  • idplatform-idThe platform id of the player.
  • scoreuint8_tThe player's individual score in the match.
• teamsarrayList of teams in the match.
  • idteam-idThe unique id for the team.
  • scoreuint8_tThe team's combined score in the match.
  • rankinguint8_tThe team's resulting rank.
  • forfeit?booleanTrue if the team has forfeited the match. (optional)

Asynchronous games

In this scenario, the game should expect to send one result per player containing only that participant's scores. The endpoint is idempotent to allow for retries, however only the first accepted result for each player will be deemed valid.

Request example

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ${XXX-secret-jwt}' \
  -d '{
    "match_id": "600f36a861246f889d381029",
    "participants": [
      {
        "id": "user_id_1",
        "score": 300
      }
    ]
  }' \
  ${config.okletsplay_url}/api/game/v1/finish

  curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ${XXX-secret-jwt}' \
  -d '{
    "match_id": "600f36a861246f889d381029",
    "participants": [
      {
        "id": "user_id_2",
        "score": 100
      }
    ]
  }' \
  ${config.okletsplay_url}/api/game/v1/finish

• match_idstringThe unique id for this match.
• participantsarrayList of participants in the match.
  • idplatform-idThe platform id of the player.
  • scoreuint8_tThe player's individual score in the match.

Forfeits

Each game is free to apply its own rules to decide when a player should be forfeit; if the forfeit occurs on the OkLetsPlay platform then we'll notify the game through the webhook, if using the push flow, or it'll be reflected in the active matches query, if using the poll flow. If the game determines a player has forfeit the game, then this information should be included in the results as follows.

Request example

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ${XXX-secret-jwt}' \
  -d '{
    "match_id": "600f36a861246f889d381029",
    "participants": [
      {
        "id": "user_id_1",
        "score": 300
      },
      {
        "id": "user_id_2",
        "score": 100
      }
    ],
    "teams": [
      {
        "id": "team_id_1",
        "score": 300,
        "ranking": 1
      },
      {
        "id": "team_id_2",
        "score": 100,
        "forfeit?": true
      }
    ]
  }' \
  ${config.okletsplay_url}/api/game/v1/finish

• match_idstringThe unique id for this match.
• participantsarrayList of participants in the match.
  • idplatform-idThe platform id of the player.
  • scoreuint8_tThe player's individual score in the match.
• teamsarrayList of teams in the match.
  • idteam-idThe unique id for the team.
  • scoreuint8_tThe team's combined score in the match.
  • rankinguint8_tThe team's resulting rank.
  • forfeit?booleanTrue if the team has forfeited the match. (optional)

Aborting A Match

A game should only be considered aborted if the game's back-end determines it has made an error. If a player crashes, disconnects, or otherwise stops competing, that player has forfeit and the other player should be considered the winner. Aborted and tied games incur no match fees for the users.

Request example

curl \
  -X POST \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer ${XXX-secret-jwt}' \
  -d '{
    "match-id": "600f36a861246f889d381029",
    "error": {
      "reason": "Something went wrong!"
    }
  }' \
  ${config.okletsplay_url}/api/game/v1/finish

• match_idstringThe unique id for this match.
• errorobjectAn object containing the error metadata.
  • reasonstringCustom error message.