558 lines
16 KiB
YAML
558 lines
16 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: PolyLAN AAndT Bot API
|
|
description: >-
|
|
Endpoints protected by the `aandt_apitoken_required` decorator
|
|
(Plamingo/pAAndT/views.py). Intended for external "apibot" integrations
|
|
that manage a single AAndT (animation/tournament) identified by the JWT
|
|
bearer token, so no per-request AAndT id is otherwise needed.
|
|
This spec was written by hand as a one-off snapshot of the current
|
|
behaviour, not generated automatically — re-check it if the views change.
|
|
version: "1.0.0"
|
|
servers:
|
|
- url: /Plamingo/aandt/api/aandt
|
|
|
|
security:
|
|
- bearerAuth: []
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
description: >-
|
|
`Authorization: Bearer <token>` header. The token is a JWT signed
|
|
with `settings.JWT_SECRET_KEY` (HS256), issuer `PolyLAN:AAndT`, and
|
|
must carry an `aandt_pk` claim identifying the target AAndT. Obtained
|
|
via `AAndT.generate_token()` (see `aandt_apibot` admin view).
|
|
|
|
responses:
|
|
Unauthorized:
|
|
description: Missing/invalid Authorization header or token
|
|
content:
|
|
text/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
example: "No Authorization header"
|
|
NotFound:
|
|
description: The AAndT (or nested match) referenced by the token/path does not exist
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
|
|
schemas:
|
|
AAndTInfos:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum: [0prep, 1publ, 3insc, 5inscdone, 7inprog, 9done, 11reviewed]
|
|
status_display:
|
|
type: string
|
|
example: "Matchs en cours"
|
|
use_teams:
|
|
type: boolean
|
|
max_entities:
|
|
type: integer
|
|
|
|
MemberUser:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
username:
|
|
type: string
|
|
tournois_alias:
|
|
type: string
|
|
nullable: true
|
|
|
|
MemberTeam:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
leader:
|
|
type: integer
|
|
nullable: true
|
|
description: pk of the leader's user, null if no leader
|
|
members:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/MemberUser"
|
|
|
|
Member:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
description: AAndTHasUserOrTeam pk
|
|
score:
|
|
type: number
|
|
done_all_matches:
|
|
type: boolean
|
|
user:
|
|
allOf:
|
|
- $ref: "#/components/schemas/MemberUser"
|
|
description: present only when the AAndT does not use teams
|
|
team:
|
|
allOf:
|
|
- $ref: "#/components/schemas/MemberTeam"
|
|
description: present only when the AAndT uses teams
|
|
|
|
MatchRoundResult:
|
|
type: object
|
|
properties:
|
|
score:
|
|
type: number
|
|
player_id:
|
|
type: integer
|
|
description: AAndTHasUserOrTeam pk
|
|
|
|
MatchRound:
|
|
type: object
|
|
properties:
|
|
round_id:
|
|
type: integer
|
|
results:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/MatchRoundResult"
|
|
|
|
Match:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: integer
|
|
title:
|
|
type: string
|
|
internal_id:
|
|
type: string
|
|
status:
|
|
type: string
|
|
enum: [waitPlayer, needConfirm, playing, done]
|
|
status_display:
|
|
type: string
|
|
rounds_count:
|
|
type: integer
|
|
use_points:
|
|
type: boolean
|
|
points_are_positions:
|
|
type: boolean
|
|
multiround_modes:
|
|
type: string
|
|
nullable: true
|
|
enum: [PA, PS, AP]
|
|
multiround_modes_display:
|
|
type: string
|
|
nullable: true
|
|
creation_date:
|
|
type: string
|
|
example: "2026-08-01 10:00:00+00:00"
|
|
playing_date:
|
|
type: string
|
|
done_date:
|
|
type: string
|
|
current_round:
|
|
type: integer
|
|
players:
|
|
type: object
|
|
description: map of AAndTHasUserOrTeam pk (string key) -> MatschHasPlayerOrTeam pk
|
|
additionalProperties:
|
|
type: integer
|
|
rounds:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/MatchRound"
|
|
|
|
Metadata:
|
|
type: object
|
|
description: Arbitrary JSON metadata stored by the bot
|
|
additionalProperties: true
|
|
|
|
SuccessResponse:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
|
|
paths:
|
|
/:
|
|
get:
|
|
operationId: aandt_api_infos
|
|
summary: Get general information about the AAndT
|
|
description: Read-only. AAndT is resolved from the bearer token.
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
aandt:
|
|
$ref: "#/components/schemas/AAndTInfos"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/members:
|
|
get:
|
|
operationId: aandt_api_members
|
|
summary: List the AAndT's registered members (users or teams)
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
members:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Member"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/matches:
|
|
get:
|
|
operationId: aandt_api_matches
|
|
summary: List all matches of the AAndT with their rounds/results
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
matches:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Match"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/metadata:
|
|
get:
|
|
operationId: aandt_api_metadata_get
|
|
summary: Get the AAndT's bot metadata
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
metadata:
|
|
$ref: "#/components/schemas/Metadata"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
post:
|
|
operationId: aandt_api_metadata_set
|
|
summary: Set the AAndT's bot metadata
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
metadata:
|
|
$ref: "#/components/schemas/Metadata"
|
|
responses:
|
|
"200":
|
|
description: Saved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SuccessResponse"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/apibot:
|
|
get:
|
|
operationId: aandt_api_apibot_get
|
|
summary: Get the AAndT's apibot activation state and display name
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
activated:
|
|
type: boolean
|
|
name:
|
|
type: string
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
post:
|
|
operationId: aandt_api_apibot_set
|
|
summary: Set the AAndT's apibot activation state and/or display name
|
|
description: Broadcasts the update over Zuperpush after saving.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
activated:
|
|
type: boolean
|
|
name:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Saved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SuccessResponse"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/message:
|
|
get:
|
|
operationId: aandt_api_message_get
|
|
summary: Get the AAndT's apibot page message
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
nullable: true
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
post:
|
|
operationId: aandt_api_message_set
|
|
summary: Set the AAndT's apibot page message
|
|
description: Broadcasts the update over Zuperpush after saving.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
message:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Saved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SuccessResponse"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/log:
|
|
post:
|
|
operationId: aandt_api_log
|
|
summary: Add a log entry to the AAndT's log (prefixed with "API:")
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [type, message]
|
|
properties:
|
|
type:
|
|
type: string
|
|
description: AAndTLog type, e.g. "info", "error"
|
|
message:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: >-
|
|
Always HTTP 200. `success` is false when the request is not a
|
|
POST, or when `type`/`message` are missing from the body.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SuccessResponse"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
|
|
/match/{pk}/metadata:
|
|
parameters:
|
|
- name: pk
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
description: Matsch pk (must belong to the token's AAndT)
|
|
get:
|
|
operationId: aandt_api_match_metadata_get
|
|
summary: Get a match's bot metadata
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
metadata:
|
|
$ref: "#/components/schemas/Metadata"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
post:
|
|
operationId: aandt_api_match_metadata_set
|
|
summary: Set a match's bot metadata
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
metadata:
|
|
$ref: "#/components/schemas/Metadata"
|
|
responses:
|
|
"200":
|
|
description: Saved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SuccessResponse"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
|
|
/match/{pk}/messages:
|
|
parameters:
|
|
- name: pk
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
description: Matsch pk (must belong to the token's AAndT)
|
|
get:
|
|
operationId: aandt_api_match_messages_get
|
|
summary: Get a match's bot messages (all/players/admin)
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
all:
|
|
type: string
|
|
nullable: true
|
|
players:
|
|
type: string
|
|
nullable: true
|
|
admin:
|
|
type: string
|
|
nullable: true
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
post:
|
|
operationId: aandt_api_match_messages_set
|
|
summary: Set one or more of a match's bot messages
|
|
description: >-
|
|
Any of `all`, `players`, `admin` may be omitted; only the keys
|
|
present in the body are updated. Triggers a Zuperpush update.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
all:
|
|
type: string
|
|
players:
|
|
type: string
|
|
admin:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Saved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SuccessResponse"
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|
|
|
|
/match/{pk}/sumbit_results:
|
|
parameters:
|
|
- name: pk
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
description: >-
|
|
Matsch pk. Must belong to the token's AAndT and currently have
|
|
status "playing", otherwise the request 404s.
|
|
post:
|
|
operationId: aandt_api_match_submit_results
|
|
summary: Submit results for the match's current round
|
|
description: >-
|
|
`round` must equal the match's current round (`Matsch.cRound()`),
|
|
otherwise the request is rejected. `results` maps a
|
|
MatschHasPlayerOrTeam pk (string key) to that participant's score
|
|
for the round (omitted participants default to 0 if `usePoints`,
|
|
else 1). Advances/finishes the match and pushes live updates.
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required: [round, results]
|
|
properties:
|
|
round:
|
|
type: integer
|
|
results:
|
|
type: object
|
|
description: map of MatschHasPlayerOrTeam pk (string) -> score (int)
|
|
additionalProperties:
|
|
type: integer
|
|
responses:
|
|
"200":
|
|
description: >-
|
|
Always HTTP 200. `success` is false with a `message` when the
|
|
request is not a POST, is missing `round`/`results`, or `round`
|
|
does not match the match's current round.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
success:
|
|
type: boolean
|
|
message:
|
|
type: string
|
|
enum: ["Missing parameters", "Wrong round"]
|
|
"401":
|
|
$ref: "#/components/responses/Unauthorized"
|
|
"404":
|
|
$ref: "#/components/responses/NotFound"
|