Custom OGS Online Leagues

OGS provide a way for organisations to run their own "league" on OGS, with a separate rank for players in the league, calculated from league games.

It's is driven by an API that the organisation can use to register players and arrange matches.

Overview

• The organisation notifies OGS of league members, providing their "membership id" and their starting league rank.
• The organisation requests matches between nominated players, providing the player-ids and optionally details of the match.
  • OGS provides a unique link to be given to each of the players, which lets them join their match
  • OGS provides a different link, which spectators can use to join the game
• When the players use their link, they arrive at a "lobby" page, where they can chat and decide when to start
  • They can also chat with spectators at this time
• When both players indicate they are ready to start, the game commences (and they are taken to it)
• The organisation can ask OGS about the status of matches at any time.
• Optionally, OGS will hit a URL provided by the organisation, to tell them when each game finishes and what the result was
• When players arrive to join the match, OGS helps them log in if they aren't already logged in, and they can register with OGS at that time if they are not already registered.

Setting up & Use

1. Get an API key from OGS - you'll need to provide an "identifier" for your League
2. Tell OGS about your members:

curl --location --request PUT 'https://beta.online-go.com/api/v1/online_league/member/crna_01' \
--header 'X-OGS-LEAGUE: COOL Go Players Association' \
--header 'X-OGS-LEAGUE-AUTH: Ge3Mqrf6JjASYaf9ZcCc64' \
--header 'Content-Type: application/json' \
--data '{"rating": 2500}'

3. Tell OGS about matches that you want to set up:

curl --location 'https://beta.online-go.com/api/v1/online_league/matches' \
--header 'X-OGS-LEAGUE: COOL Go Players Association'' \
--header 'X-OGS-LEAGUE-AUTH: Ge3Mqrf6JjASYaf9ZcCc64' \
--header 'Content-Type: application/json' \
--header 'Cookie: csrftoken=Od0zZQiVhjLJ04Qc69w7jOljEU8TZMaBhyOTOQtVhI8ilaZl1vcGIe8QwYW6iZew' \
--data '{"black_member_id": "crna_01", "white_member_id": "crna_02", "league_match_id": "Inaugral-01", "handicap": "-1"}'

In the reply, OGS provides these things:

    "id": 11016,
    "black_invite": "https://beta.online-go.com/online-league/league-player?side=black&id=3wYqA5bY5RanHTzPgBHePJ",
    "white_invite": "https://beta.online-go.com/online-league/league-player?side=white&id=3nu6A7zAtGtyXd5nSwmVfD",
    "spectator_link": "https://beta.online-go.com/online-league/league-game/11016",

Provide each of the links to the appropriate people.

Note that only the actual player should get the invite - no-one else.

4. Use the "id" to ask about the status of the game:

curl --location --request GET 'https://beta.online-go.com/api/v1/online_league/matches/11016'
--header 'X-OGS-LEAGUE: COOL Go Players Association'
--header 'X-OGS-LEAGUE-AUTH: Ge3Mqrf6JjASYaf9ZcCc64'
--header 'Content-Type: application/json'
--data '{}'

5. Optionally, arrange for OGS to call you when the match is done:

curl --location --request PUT 'https://beta.online-go.com/api/v1/online_league/callback'
--header 'X-OGS-LEAGUE: COOL Go Players Association'
--header 'X-OGS-LEAGUE-AUTH: Ge3Mqrf6JjASYaf9ZcCc64'
--header 'Content-Type: application/json'
--data '{"callback_url_template": "http://www.cool_go_players.com/game_update/{id}"}'

... OGS will GET to http://www.cool_go_players.com/game_update/{id} when each game finishes, with id set to the game id.

Note that your API needs to be available and return a 200 for id 0 at the time that you set this callback, so that OGS can test it.