nikola/pairgoth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation for API, configuration, and model

Browse Source 
API.md:
- Add export formats (JSON, XML, EGF, FFG, CSV)
- Document /explain endpoint for pairing analysis
- Add PUT /standings for freezing
- Improve parameter documentation
- Fix typos (regitration -> registration, #tip -> #tid)

configuration.md:
- Add property loading hierarchy
- Document SSL/TLS configuration
- Add OAuth provider configuration
- Add ratings.path property
- Include example configurations

model.md:
- Complete entity diagram with Team, external IDs
- Document all tournament types (PAIRGO, RENGO, TEAM)
- Add TimeSystem types and parameters
- Document all pairing parameters
- List all 39 tiebreak criteria
- Add external database (AGA, EGF, FFG) documentation
This commit is contained in:
Claude Brisson
2025-11-29 08:05:53 +01:00
parent 8ca25ec421
commit 662f438cee
5 changed files with 827 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

271
doc/API.md
View File

@@ -2,158 +2,285 @@
## General remarks
The API expects an `Accept` header of `application/json`, with no encoding or an `UTF-8` encoding. Exceptions are some export operations which can have different MIME types to specify the expected format.
The API expects an `Accept` header of `application/json`, with no encoding or an `UTF-8` encoding. Exceptions are some export operations which can have different MIME types to specify the expected format:
- `application/json` - JSON output (default)
- `application/xml` - OpenGotha XML export
- `application/egf` - EGF format
- `application/ffg` - FFG format
- `text/csv` - CSV format
GET requests return either an array or an object, as specified below.
POST, PUT and DELETE requests return either the 200 HTTP code with `{ "success": true }` (with an optional `"id"` field for some POST requests), or and invalid HTTP code and (for some errors) the body `{ "success": false, "error": <error message> }`.
POST, PUT and DELETE requests return either the 200 HTTP code with `{ "success": true }` (with an optional `"id"` field for some POST requests), or an invalid HTTP code and (for some errors) the body `{ "success": false, "error": <error message> }`.
All POST/PUT/DELETE requests use read/write locks for concurrency. GET requests use read locks.
When authentication is enabled, all requests require an `Authorization` header.
## Synopsis
+ /api/tour GET POST Tournaments handling
+ /api/tour/#tid GET PUT DELETE Tournaments handling
+ /api/tour/#tid/part GET POST Registration handling
+ /api/tour/#tid/part/#pid GET PUT DELETE Registration handling
+ /api/tour/#tid/team GET POST Team handling
+ /api/tour/#tid/team/#tid GET PUT DELETE Team handling
+ /api/tour/#tid/pair/#rn GET POST PUT DELETE Pairing
+ /api/tour/#tid/res/#rn GET PUT DELETE Results
+ /api/tour/#tid/standings GET Standings
+ /api/tour/#tid/stand/#rn GET Standings
+ /api/tour GET POST Tournaments handling
+ /api/tour/#tid GET PUT DELETE Tournaments handling
+ /api/tour/#tid/part GET POST Registration handling
+ /api/tour/#tid/part/#pid GET PUT DELETE Registration handling
+ /api/tour/#tid/team GET POST Team handling
+ /api/tour/#tid/team/#tid GET PUT DELETE Team handling
+ /api/tour/#tid/pair/#rn GET POST PUT DELETE Pairing
+ /api/tour/#tid/res/#rn GET PUT DELETE Results
+ /api/tour/#tid/standings GET PUT Standings
+ /api/tour/#tid/stand/#rn GET Standings
+ /api/tour/#tid/explain/#rn GET Pairing explanation
+ /api/token GET POST DELETE Authentication
## Tournament handling
+ `GET /api/tour` Get a list of known tournaments ids
*output* json map (id towards shortName) of known tournaments (subject to change)
*output* json map (id towards shortName) of known tournaments
+ `GET /api/tour/#tid` Get the details of tournament #tid
*output* json object for tournament #tid
Supports `Accept: application/xml` to get OpenGotha XML export.
+ `POST /api/tour` Create a new tournament
*input* json object for new tournament (see `Tournament.fromJson` in the sources)
*input* json object for new tournament, or OpenGotha XML with `Content-Type: application/xml`
Tournament JSON structure:
```json
{
"type": "INDIVIDUAL",
"name": "Tournament Name",
"shortName": "TN",
"startDate": "2024-01-15",
"endDate": "2024-01-16",
"country": "fr",
"location": "Paris",
"online": false,
"rounds": 5,
"gobanSize": 19,
"rules": "FRENCH",
"komi": 7.5,
"timeSystem": { ... },
"pairing": { ... }
}
```
Tournament types: `INDIVIDUAL`, `PAIRGO`, `RENGO2`, `RENGO3`, `TEAM2`, `TEAM3`, `TEAM4`, `TEAM5`
*output* `{ "success": true, "id": #tid }`
+ `PUT /api/tour/#tid` Modify a tournament
*input* json object for updated tournament (only id and updated fields required)
*output* `{ "success": true }`
+ `DELETE /api/tour/#tid` Delete a tournament
*output* `{ "success": true }`
## Players handling
+ `GET /api/tour/#tid/part` Get a list of registered players
*output* json array of known players
+ `GET /api/tour/#tid/part/#pid` Get regitration details for player #pid
+ `GET /api/tour/#tid/part/#pid` Get registration details for player #pid
*output* json object for player #pid
+ `POST /api/tour/#tid/part` Register a new player
*input* `{ "name":"..." , "firstname":"..." , "rating":<rating> , "rank":<rank> , "country":"XX" [ , "club":"Xxxx" ] [ , "final":true/false ] [ , "mmsCorrection":0 ] }`
*input*
```json
{
"name": "Lastname",
"firstname": "Firstname",
"rating": 1500,
"rank": -5,
"country": "FR",
"club": "Club Name",
"final": true,
"mmsCorrection": 0,
"egfId": "12345678",
"ffgId": "12345",
"agaId": "12345"
}
```
Rank values: -30 (30k) to 8 (9D). Rating in EGF-style (100 = 1 stone).
*output* `{ "success": true, "id": #pid }`
+ `PUT /api/tour/#tid/part/#pid` Modify a player registration
*input* json object for updated registration (only id and updated fields required)
*output* `{ "success": true }`
+ `DELETE /api/tour/#tid/part/#pid` Delete a player registration
*input* `{ "id": #pid }`
*output* `{ "success": true }`
## Teams handling
For team tournaments (PAIRGO, RENGO2, RENGO3, TEAM2-5).
+ `GET /api/tour/#tid/team` Get a list of registered teams
*output* json array of known teams
+ `GET /api/tour/#tid/team/#tid` Get regitration details for team #tid
+ `GET /api/tour/#tid/team/#teamid` Get registration details for team #teamid
*output* json object for team #tid
*output* json object for team #teamid
+ `POST /api/tour/#tid/team` Register a new team
*input* json object for new team
*output* `{ "success": true, "id": #tid }`
+ `PUT /api/tour/#tid/team/#tid` Modify a team registration
*input*
```json
{
"name": "Team Name",
"playerIds": [1, 2, 3],
"final": true,
"mmsCorrection": 0
}
```
*output* `{ "success": true, "id": #teamid }`
+ `PUT /api/tour/#tid/team/#teamid` Modify a team registration
*input* json object for updated registration (only id and updated fields required)
*output* `{ "success": true }`
+ `DELETE /api/tour/#tid/team/#tid` Delete a team registration
*input* `{ "id": #tid }`
+ `DELETE /api/tour/#tid/team/#teamid` Delete a team registration
*output* `{ "success": true }`
## Pairing
+ `GET /api/tour/#tid/pair/#rn` Get pairable players for round #rn
*output* `{ "games": [ games... ], "pairables:" [ #pid, ... of players not skipping and not playing the round ], "unpairables": [ #pid, ... of players skipping the round ] }`
+ `POST /api/tour/#tip/pair/#n` Generate pairing for round #n and given players (or string "all") ; error if already generated for provided players
*output*
```json
{
"games": [ { "id": 1, "t": 1, "w": 2, "b": 3, "h": 0 }, ... ],
"pairables": [ 4, 5, ... ],
"unpairables": [ 6, 7, ... ]
}
```
- `games`: existing pairings for the round
- `pairables`: player IDs available for pairing (not skipping, not already paired)
- `unpairables`: player IDs skipping the round
+ `POST /api/tour/#tid/pair/#rn` Generate pairing for round #rn
*input* `[ "all" ]` or `[ #pid, ... ]`
Optional query parameters:
- `legacy=true` - Use legacy pairing algorithm
- `weights_output=<file>` - Output weights to file for debugging
- `append=true` - Append to weights output file
*output* `[ { "id": #gid, "t": table, "w": #wpid, "b": #bpid, "h": handicap }, ... ]`
+ `PUT /api/tour/#tip/pair/#n` Manual pairing (with optional handicap)
+ `PUT /api/tour/#tid/pair/#rn` Manual pairing or table renumbering
For manual pairing:
*input* `{ "id": #gid, "w": #wpid, "b": #bpid, "h": <handicap> }`
For table renumbering:
*input* `{ "renumber": <game_id or null>, "orderBy": "mms" | "table" }`
*output* `{ "success": true }`
+ `DELETE /api/tour/#tip/pair/#n` Delete pairing for round #n and given players (or string "all") ; games with results entered are skipped
+ `DELETE /api/tour/#tid/pair/#rn` Delete pairing for round #rn
*input* `[ "all" ]` or `[ #gid, ... ]`
Games with results already entered are skipped unless `"all"` is specified.
*output* `{ "success": true }`
## Results
+ `GET /api/tour/#tip/res/#rn` Get results for round #rn
*output* `[ { "id": #gid, "res": <result> } ]` with `res` being one of: `"w"`, `"b"`, `"="` (jigo), `"x"` (cancelled),`"?"` (unknown), `"#"` (both win), or `"0"` (both loose).
+ `PUT /api/tour/#tip/res/#rn` Save a result (or put it back to unknown)
*input* `{ "id": #gid, "res": <result> }` with `res` being one of: `"w"`, `"b"`, `"="` (jigo), `"x"` (cancelled)
+ `GET /api/tour/#tid/res/#rn` Get results for round #rn
*output* `[ { "id": #gid, "res": <result> }, ... ]`
Result codes:
- `"w"` - White won
- `"b"` - Black won
- `"="` - Jigo (draw)
- `"X"` - Cancelled
- `"?"` - Unknown (not yet played)
- `"#"` - Both win (unusual)
- `"0"` - Both lose (unusual)
+ `PUT /api/tour/#tid/res/#rn` Save a result
*input* `{ "id": #gid, "res": <result> }`
*output* `{ "success": true }`
+ `DELETE /api/tour/#tip/res/#rn` Clear all results (put back all results to unknown)
+ `DELETE /api/tour/#tid/res/#rn` Clear all results for round
*input* none
*output* `{ "success": true }`
*output* `{ "success": true }`
## Standings
+ `GET /api/tour/#tid/stand/#rn` Get standings after round #rn (or initial standings for round '0')
*output* `[ { "id": #pid, "place": place, "<crit>": double }, ... ]`
where `<crit>` is the name of a criterium, among "score", "nbw", "mms", "sosm", "sososm", ...
+ `GET /api/tour/#tid/standings` Get standings after final round
*output* `[ { "id": #pid, "place": place, "<crit>": value }, ... ]`
Supports multiple output formats via Accept header:
- `application/json` - JSON (default)
- `application/egf` - EGF format
- `application/ffg` - FFG format
- `text/csv` - CSV format
Optional query parameters:
- `include_preliminary=true` - Include preliminary standings
- `individual_standings=true` - For team tournaments with individual scoring
+ `GET /api/tour/#tid/stand/#rn` Get standings after round #rn
Use round `0` for initial standings.
*output* `[ { "id": #pid, "place": place, "<crit>": value }, ... ]`
Criteria names include: `nbw`, `mms`, `sts`, `cps`, `sosw`, `sosm`, `sososw`, `sososm`, `sodosw`, `sodosm`, `cussw`, `cussm`, `dc`, `sdc`, `ext`, `exr`, etc.
+ `PUT /api/tour/#tid/standings` Freeze/lock standings
*output* `{ "success": true }`
## Pairing explanation
+ `GET /api/tour/#tid/explain/#rn` Get detailed pairing criteria weights for round #rn
*output* Detailed pairing weight analysis and criteria breakdown
Used for debugging and understanding pairing decisions.
## Authentication
+ `GET /api/token` Get the token of the currently logged user, or give an error.
+ `GET /api/token` Check authentication status
+ `POST /api/token` Create an access token. Expects an authentication json object.
*output* Token information for the currently logged user, or error if not authenticated.
+ `DELETE /api/token` Delete the token of the currently logged user.
+ `POST /api/token` Create an access token
*input* Authentication credentials (format depends on auth mode)
*output* `{ "success": true, "token": "..." }`
+ `DELETE /api/token` Logout / revoke token
*output* `{ "success": true }`