v0.5.0 user support with auth added, tests and doc updated
This commit is contained in:
167
doc/api.md
167
doc/api.md
@ -4,12 +4,92 @@ Base URL: `http://localhost:8080/api/v1`
|
||||
|
||||
Content-Type: `application/json` (required for POST/PUT)
|
||||
|
||||
## Endpoints
|
||||
## Authentication
|
||||
|
||||
The API supports optional JWT authentication for user accounts. When authenticated, games are associated with the user account.
|
||||
|
||||
### Register User
|
||||
`POST /auth/register`
|
||||
|
||||
Creates new user account and returns JWT token.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"username": "alice",
|
||||
"email": "alice@example.com",
|
||||
"password": "SecurePass123"
|
||||
}
|
||||
```
|
||||
|
||||
- `username` (string, required): 1-40 characters, alphanumeric and underscore only
|
||||
- `email` (string, optional): Valid email address
|
||||
- `password` (string, required): Minimum 8 characters, must contain letter and number
|
||||
|
||||
**Response (201):**
|
||||
```json
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"userId": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"username": "alice",
|
||||
"email": "alice@example.com",
|
||||
"expiresAt": "2025-01-14T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Login
|
||||
`POST /auth/login`
|
||||
|
||||
Authenticates user and returns JWT token.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"identifier": "alice",
|
||||
"password": "SecurePass123"
|
||||
}
|
||||
```
|
||||
|
||||
- `identifier` (string, required): Username or email address
|
||||
- `password` (string, required): User password
|
||||
|
||||
**Response (200):**
|
||||
```json
|
||||
{
|
||||
"token": "eyJhbGciOiJIUzI1NiIs...",
|
||||
"userId": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"username": "alice",
|
||||
"email": "alice@example.com",
|
||||
"expiresAt": "2025-01-14T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
### Get Current User
|
||||
`GET /auth/me`
|
||||
|
||||
Returns authenticated user information. Requires authentication.
|
||||
|
||||
**Headers:**
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Response (200):**
|
||||
```json
|
||||
{
|
||||
"userId": "550e8400-e29b-41d4-a716-446655440000",
|
||||
"username": "alice",
|
||||
"email": "alice@example.com",
|
||||
"createdAt": "2025-01-07T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Game Endpoints
|
||||
|
||||
### Health Check
|
||||
`GET /health`
|
||||
|
||||
Returns server status.
|
||||
Returns server and storage status.
|
||||
|
||||
**Response (200):**
|
||||
```json
|
||||
@ -22,13 +102,18 @@ Returns server status.
|
||||
|
||||
Storage states:
|
||||
- `"disabled"` - No storage path configured
|
||||
- `"ok"` - Database operational
|
||||
- `"ok"` - Database operational with auth enabled
|
||||
- `"degraded"` - Write failures detected, operating memory-only
|
||||
|
||||
### Create Game
|
||||
`POST /games`
|
||||
|
||||
Creates new game with specified players.
|
||||
Creates new game with specified players. Optional authentication associates game with user.
|
||||
|
||||
**Headers (optional):**
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
@ -47,11 +132,6 @@ Creates new game with specified players.
|
||||
}
|
||||
```
|
||||
|
||||
- `type` (integer, required): 1=human, 2=computer
|
||||
- `level` (integer, 0-20): Engine skill level for computer players
|
||||
- `searchTime` (integer, 100-10000ms): Engine thinking time for computer players
|
||||
- `fen` (string): Starting position in FEN notation (default: standard position)
|
||||
|
||||
**Response (201):**
|
||||
```json
|
||||
{
|
||||
@ -61,37 +141,19 @@ Creates new game with specified players.
|
||||
"state": "ongoing",
|
||||
"moves": [],
|
||||
"players": {
|
||||
"white": {"id": "...", "color": 1, "type": 1},
|
||||
"black": {"id": "...", "color": 2, "type": 2, "level": 15, "searchTime": 1000}
|
||||
"white": {"id": "550e8400-...", "color": 1, "type": 1},
|
||||
"black": {"id": "ai-player-...", "color": 2, "type": 2, "level": 15, "searchTime": 1000}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Note: When authenticated, human player IDs match the user's ID. Anonymous players receive unique UUIDs.
|
||||
|
||||
### Get Game
|
||||
`GET /games/{gameId}`
|
||||
|
||||
Returns current game state.
|
||||
|
||||
**Response (200):**
|
||||
```json
|
||||
{
|
||||
"gameId": "...",
|
||||
"fen": "...",
|
||||
"turn": "w",
|
||||
"state": "ongoing",
|
||||
"moves": ["e2e4", "e7e5"],
|
||||
"players": {...},
|
||||
"lastMove": {
|
||||
"move": "e7e5",
|
||||
"playerColor": "b",
|
||||
"score": 25,
|
||||
"depth": 12
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
States: `ongoing`, `pending` (computer thinking), `white wins`, `black wins`, `draw`, `stalemate`
|
||||
|
||||
### Make Move
|
||||
`POST /games/{gameId}/moves`
|
||||
|
||||
@ -107,53 +169,27 @@ Submits human move or triggers computer move.
|
||||
{"move": "cccc"}
|
||||
```
|
||||
|
||||
Returns updated game state (200) or error (400).
|
||||
|
||||
### Undo Moves
|
||||
`POST /games/{gameId}/undo`
|
||||
|
||||
Reverts moves from history.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{"count": 2}
|
||||
```
|
||||
|
||||
- `count` (integer, 1-300): Number of moves to undo (default: 1)
|
||||
|
||||
### Configure Players
|
||||
`PUT /games/{gameId}/players`
|
||||
|
||||
Changes player configuration mid-game.
|
||||
|
||||
**Request:**
|
||||
```json
|
||||
{
|
||||
"white": {"type": 2, "level": 5, "searchTime": 100},
|
||||
"black": {"type": 1}
|
||||
}
|
||||
```
|
||||
|
||||
### Get Board
|
||||
`GET /games/{gameId}/board`
|
||||
|
||||
Returns ASCII board visualization.
|
||||
|
||||
**Response (200):**
|
||||
```json
|
||||
{
|
||||
"fen": "...",
|
||||
"board": " a b c d e f g h\n8 r n b q k b n r 8\n..."
|
||||
}
|
||||
```
|
||||
|
||||
### Delete Game
|
||||
`DELETE /games/{gameId}`
|
||||
|
||||
Removes game from memory. Returns 204 on success.
|
||||
|
||||
## Error Format
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "Description",
|
||||
@ -170,10 +206,23 @@ Error codes:
|
||||
- `RATE_LIMIT_EXCEEDED` - Request limit exceeded
|
||||
- `INVALID_REQUEST` - Malformed request
|
||||
- `INVALID_CONTENT_TYPE` - Missing/wrong Content-Type header
|
||||
- `INVALID_FEN` - Invalid FEN format
|
||||
- `INTERNAL_ERROR` - Server error
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
- Standard: 10 request/second/IP
|
||||
- Standard: 10 requests/second/IP (general endpoints)
|
||||
- Development (`-dev`): 20 requests/second/IP
|
||||
- Registration: 5 requests/minute/IP
|
||||
- Login: 10 requests/minute/IP
|
||||
|
||||
Exceeding limit returns 429 status.
|
||||
Exceeding limit returns 429 status.
|
||||
|
||||
## JWT Token Format
|
||||
|
||||
Tokens are HS256-signed JWTs valid for 7 days. Include in Authorization header:
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
|
||||
Token claims include `sub` (user ID), `username`, `email`, and `exp` (expiration).
|
||||
Reference in New Issue
Block a user