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 driven by an API that the organisation can use to register players and arrange matches.

Overview

Using the OGS COOL API:

• 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

Note: the way you get this key is by getting in contact with someone from OGS who can give you one. This is most likely anoek, maybe also GreenAsJade. They will want to know something about what you intend to do with it, to make sure it's properly used, that they know who's using it, and that you're properly supported.

2. Tell OGS about your members.

Something like:

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: API-key-here' \
--header 'Content-Type: application/json' \
--data '{"rating": 2500}'

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

Something like:

curl --location --request POST 'https://beta.online-go.com/api/v1/online_league/matches' \
--header 'X-OGS-LEAGUE: COOL Go Players Association'' \
--header 'X-OGS-LEAGUE-AUTH: API-key-here' \
--header 'Content-Type: application/json' \
--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 (and a ton of other information):

    "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:

Something like:

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: API-key-here' \
--header 'Content-Type: application/json' \
--data '{}'

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

Something like:

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: API-key-here' \
--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.