From 6a5a910554726973c16d5ebe3d6b017e0cfebed3 Mon Sep 17 00:00:00 2001 From: Thibault Duplessis Date: Sat, 8 Jun 2024 10:44:07 +0200 Subject: [PATCH] document /api/broadcast/top --- doc/specs/lichess-api.yaml | 3 + doc/specs/schemas/BroadcastTop.yaml | 36 +++ doc/specs/schemas/BroadcastWithLastRound.yaml | 9 + .../broadcasts/api-broadcasts-official.yaml | 224 +++++++++--------- .../tags/broadcasts/api-broadcasts-top.yaml | 29 +++ 5 files changed, 189 insertions(+), 112 deletions(-) create mode 100644 doc/specs/schemas/BroadcastTop.yaml create mode 100644 doc/specs/schemas/BroadcastWithLastRound.yaml create mode 100644 doc/specs/tags/broadcasts/api-broadcasts-top.yaml diff --git a/doc/specs/lichess-api.yaml b/doc/specs/lichess-api.yaml index 26f8676..8bde702 100644 --- a/doc/specs/lichess-api.yaml +++ b/doc/specs/lichess-api.yaml @@ -437,6 +437,9 @@ paths: /api/broadcast: $ref: './tags/broadcasts/api-broadcasts-official.yaml' + /api/broadcast/top: + $ref: './tags/broadcasts/api-broadcasts-top.yaml' + /api/broadcast/by/{username}: $ref: './tags/broadcasts/api-broadcasts-by-user.yaml' diff --git a/doc/specs/schemas/BroadcastTop.yaml b/doc/specs/schemas/BroadcastTop.yaml new file mode 100644 index 0000000..7e1d8f2 --- /dev/null +++ b/doc/specs/schemas/BroadcastTop.yaml @@ -0,0 +1,36 @@ +type: object + +properties: + active: + type: array + items: + $ref: "./BroadcastWithLastRound.yaml" + upcoming: + type: array + items: + $ref: "./BroadcastWithLastRound.yaml" + past: + type: object + properties: + currentPage: + type: number + example: 4 + maxPerPage: + type: number + example: 20 + currentPageResults: + type: array + items: + $ref: "./BroadcastWithLastRound.yaml" + nbResults: + type: number + example: 205194 + previousPage: + type: [number, "null"] + example: 3 + nextPage: + type: [number, "null"] + example: 5 + nbPages: + type: number + example: 13680 diff --git a/doc/specs/schemas/BroadcastWithLastRound.yaml b/doc/specs/schemas/BroadcastWithLastRound.yaml new file mode 100644 index 0000000..fab6e51 --- /dev/null +++ b/doc/specs/schemas/BroadcastWithLastRound.yaml @@ -0,0 +1,9 @@ +type: object + +properties: + group: + type: string + tour: + $ref: "./BroadcastTour.yaml" + lastRound: + $ref: "./BroadcastRoundInfo.yaml" diff --git a/doc/specs/tags/broadcasts/api-broadcasts-official.yaml b/doc/specs/tags/broadcasts/api-broadcasts-official.yaml index 940ad5c..05a5bed 100644 --- a/doc/specs/tags/broadcasts/api-broadcasts-official.yaml +++ b/doc/specs/tags/broadcasts/api-broadcasts-official.yaml @@ -17,7 +17,7 @@ get: default: 20 minimum: 1 responses: - '200': + "200": description: The list of official broadcasts. headers: Access-Control-Allow-Origin: @@ -27,115 +27,115 @@ get: content: application/x-ndjson: schema: - $ref: '../../schemas/BroadcastWithRounds.yaml' + $ref: "../../schemas/BroadcastWithRounds.yaml" example: - { - 'tour': - { - 'id': 'qkY2yAcs', - 'name': 'Norway Chess 2024 | Open', - 'slug': 'norway-chess-2024--open', - 'description': 'May 27th - June 7th | 6-player double round-robin | Classical time control | Carlsen, Ding, Caruana, Nakamura', - 'createdAt': 1716672627410, - 'tier': 5, - 'image': 'https://image.lichess1.org/display?h=400&op=thumbnail&path=aaarmstark:relay:qkY2yAcs:dCwnFf0q.jpg&w=800&sig=36d5da931b2f9631e3ad4ae67cdb6b6412c469bb', - 'markup': "

The Norway Chess 2024 is a 6-player double round-robin tournament, held from the 27th of May to the 7th of June in Stavanger, Norway, featuring the former and current World Champions Magnus Carlsen and Ding Liren, Fabiano Caruana, Hikaru Nakamura, R Praggnanandhaa and Alireza Firouzja.

\n

Time control is 120 minutes for the entire game with a 10-second increment from move 41.

\n

Official Website | Standings | Regulations

\n
\n

Mutually agreed draws are not allowed until both players have made at least 30 moves.

\n

In the event of a draw, an Armageddon game is played to determine the winner of the round. Players keep the colour from the classical game. Time control is 10 minutes for White and 7 minutes for Black with a 1-second increment from move 41.

\n
\n

Standings after Round 5

\n

Players are awarded:

\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n
RankPlayerEloWDLAwTotal
1GM Nakamura2794230210.0
2GM Carlsen283022129.0
3GM Praggnanandhaa274722118.5
4GM Firouzja273713116.5
5GM Caruana280512205.0
6GM Ding276202312.5
\n
\n
\n

Previous editions: 2023 | 2022 | 2021

\n", - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/qkY2yAcs', - }, - 'rounds': - [ - { - 'id': 'VFMWFVLX', - 'name': 'Round 5', - 'slug': 'round-5', - 'createdAt': 1716681349783, - 'finished': true, - 'startsAt': 1717254000000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-5/VFMWFVLX', - }, - { - 'id': '4JSenCaJ', - 'name': 'Round 4', - 'slug': 'round-4', - 'createdAt': 1716681322100, - 'finished': true, - 'startsAt': 1717081200000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-4/4JSenCaJ', - }, - { - 'id': 'xmZcMs9U', - 'name': 'Round 3', - 'slug': 'round-3', - 'createdAt': 1716681206009, - 'finished': true, - 'startsAt': 1716994800000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-3/xmZcMs9U', - }, - { - 'id': 'sbOHYOVj', - 'name': 'Round 2', - 'slug': 'round-2', - 'createdAt': 1716673477425, - 'finished': true, - 'startsAt': 1716908400000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-2/sbOHYOVj', - }, - { - 'id': 'I9TLGEOt', - 'name': 'Round 1', - 'slug': 'round-1', - 'createdAt': 1716672669495, - 'finished': true, - 'startsAt': 1716822000000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-1/I9TLGEOt', - }, - { - 'id': 'E0YSbWDC', - 'name': 'Tiebreaks', - 'slug': 'tiebreaks', - 'createdAt': 1716681627336, - 'startsAt': 1717790400000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/tiebreaks/E0YSbWDC', - }, - { - 'id': 'C5Zzd9mM', - 'name': 'Round 10', - 'slug': 'round-10', - 'createdAt': 1716681541792, - 'startsAt': 1717772400000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-10/C5Zzd9mM', - }, - { - 'id': 'Qvlkp2yF', - 'name': 'Round 9', - 'slug': 'round-9', - 'createdAt': 1716681503527, - 'startsAt': 1717686000000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-9/Qvlkp2yF', - }, - { - 'id': '2xhPECG3', - 'name': 'Round 8', - 'slug': 'round-8', - 'createdAt': 1716681472192, - 'startsAt': 1717513200000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-8/2xhPECG3', - }, - { - 'id': '4FLBpAW3', - 'name': 'Round 7', - 'slug': 'round-7', - 'createdAt': 1716681411436, - 'startsAt': 1717426800000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-7/4FLBpAW3', - }, - { - 'id': 'Whq5YPU7', - 'name': 'Round 6', - 'slug': 'round-6', - 'createdAt': 1716681379848, - 'startsAt': 1717340400000, - 'url': 'https://lichess.org/broadcast/norway-chess-2024--open/round-6/Whq5YPU7', - }, - ], - } + { + "tour": + { + "id": "qkY2yAcs", + "name": "Norway Chess 2024 | Open", + "slug": "norway-chess-2024--open", + "description": "May 27th - June 7th | 6-player double round-robin | Classical time control | Carlsen, Ding, Caruana, Nakamura", + "createdAt": 1716672627410, + "tier": 5, + "image": "https://image.lichess1.org/display?h=400&op=thumbnail&path=aaarmstark:relay:qkY2yAcs:dCwnFf0q.jpg&w=800&sig=36d5da931b2f9631e3ad4ae67cdb6b6412c469bb", + "markup": "

The Norway Chess 2024 is a 6-player double round-robin tournament, held from the 27th of May to the 7th of June in Stavanger, Norway, featuring the former and current World Champions Magnus Carlsen and Ding Liren, Fabiano Caruana, Hikaru Nakamura, R Praggnanandhaa and Alireza Firouzja.

\n

Time control is 120 minutes for the entire game with a 10-second increment from move 41.

\n

Official Website | Standings | Regulations

\n
\n

Mutually agreed draws are not allowed until both players have made at least 30 moves.

\n

In the event of a draw, an Armageddon game is played to determine the winner of the round. Players keep the colour from the classical game. Time control is 10 minutes for White and 7 minutes for Black with a 1-second increment from move 41.

\n
\n

Standings after Round 5

\n

Players are awarded:

\n\n
\n\n\n\n\n\n\n\n\n\n\n\n\n
RankPlayerEloWDLAwTotal
1GM Nakamura2794230210.0
2GM Carlsen283022129.0
3GM Praggnanandhaa274722118.5
4GM Firouzja273713116.5
5GM Caruana280512205.0
6GM Ding276202312.5
\n
\n
\n

Previous editions: 2023 | 2022 | 2021

\n", + "url": "https://lichess.org/broadcast/norway-chess-2024--open/qkY2yAcs", + }, + "rounds": + [ + { + "id": "VFMWFVLX", + "name": "Round 5", + "slug": "round-5", + "createdAt": 1716681349783, + "finished": true, + "startsAt": 1717254000000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-5/VFMWFVLX", + }, + { + "id": "4JSenCaJ", + "name": "Round 4", + "slug": "round-4", + "createdAt": 1716681322100, + "finished": true, + "startsAt": 1717081200000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-4/4JSenCaJ", + }, + { + "id": "xmZcMs9U", + "name": "Round 3", + "slug": "round-3", + "createdAt": 1716681206009, + "finished": true, + "startsAt": 1716994800000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-3/xmZcMs9U", + }, + { + "id": "sbOHYOVj", + "name": "Round 2", + "slug": "round-2", + "createdAt": 1716673477425, + "finished": true, + "startsAt": 1716908400000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-2/sbOHYOVj", + }, + { + "id": "I9TLGEOt", + "name": "Round 1", + "slug": "round-1", + "createdAt": 1716672669495, + "finished": true, + "startsAt": 1716822000000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-1/I9TLGEOt", + }, + { + "id": "E0YSbWDC", + "name": "Tiebreaks", + "slug": "tiebreaks", + "createdAt": 1716681627336, + "startsAt": 1717790400000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/tiebreaks/E0YSbWDC", + }, + { + "id": "C5Zzd9mM", + "name": "Round 10", + "slug": "round-10", + "createdAt": 1716681541792, + "startsAt": 1717772400000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-10/C5Zzd9mM", + }, + { + "id": "Qvlkp2yF", + "name": "Round 9", + "slug": "round-9", + "createdAt": 1716681503527, + "startsAt": 1717686000000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-9/Qvlkp2yF", + }, + { + "id": "2xhPECG3", + "name": "Round 8", + "slug": "round-8", + "createdAt": 1716681472192, + "startsAt": 1717513200000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-8/2xhPECG3", + }, + { + "id": "4FLBpAW3", + "name": "Round 7", + "slug": "round-7", + "createdAt": 1716681411436, + "startsAt": 1717426800000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-7/4FLBpAW3", + }, + { + "id": "Whq5YPU7", + "name": "Round 6", + "slug": "round-6", + "createdAt": 1716681379848, + "startsAt": 1717340400000, + "url": "https://lichess.org/broadcast/norway-chess-2024--open/round-6/Whq5YPU7", + }, + ], + } diff --git a/doc/specs/tags/broadcasts/api-broadcasts-top.yaml b/doc/specs/tags/broadcasts/api-broadcasts-top.yaml new file mode 100644 index 0000000..13a1222 --- /dev/null +++ b/doc/specs/tags/broadcasts/api-broadcasts-top.yaml @@ -0,0 +1,29 @@ +get: + operationId: broadcastsTop + summary: Get paginated top broadcast previews + description: | + The same data, in the same order, as can be seen on [https://lichess.org/broadcast](/broadcast). + tags: + - Broadcasts + security: [] + parameters: + - in: query + name: page + description: Which page to fetch. Only page 1 has "active" and "upcoming" broadcasts. + schema: + type: integer + default: 1 + minimum: 1 + maximum: 20 + responses: + "200": + description: Paginated top broadcast previews. + headers: + Access-Control-Allow-Origin: + schema: + type: string + default: "'*'" + content: + application/x-ndjson: + schema: + $ref: "../../schemas/BroadcastTop.yaml"