# API Endpoints

REST API reference for `dance-lessons-coach`. Extracted from the original `AGENTS.md` (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe.

## Base URL

```
http://localhost:8080
```

## OpenAPI Documentation

- **Swagger UI:** `http://localhost:8080/swagger/`
- **OpenAPI Spec:** `http://localhost:8080/swagger/doc.json`

The API provides interactive documentation using Swagger UI with complete OpenAPI 2.0 specification. All endpoints, request/response models, and validation rules are documented using a **hierarchical tagging system**.

**Features:**

- Interactive API exploration with hierarchical organization
- Try-it-out functionality for all endpoints
- Model schemas with examples
- Response examples with validation rules
- Hierarchical tag structure for better navigation

**Generation:** Documentation is auto-generated from code annotations using [swaggo/swag](https://github.com/swaggo/swag) with the command:

```bash
go generate ./pkg/server/
```

**Tag Organization:**

- `API/v1/Greeting` — Version 1 greeting endpoints
- `API/v2/Greeting` — Version 2 greeting endpoints
- `System/Health` — Health and readiness endpoints

**Hierarchical Benefits:**

- Clear separation between API domains (API vs System)
- Version organization within each domain
- Natural hierarchy in Swagger UI
- Scalable for future API growth

**Embedded Documentation:** The OpenAPI spec is embedded in the binary using Go's `//go:embed` directive for single-binary deployment.

---

## Health Check

```http
GET /api/health
```

**Response:**

```json
{"status":"healthy"}
```

## Version Info

```http
GET /api/version
GET /api/version?format=plain
GET /api/version?format=full
GET /api/version?format=json
```

Returns the running binary version (injected at build time via `-ldflags`). The `format` query parameter controls the response shape:

- `format=plain` (or `?format=short`): plain text version (e.g. `1.0.0`)
- `format=full`: detailed multi-line text (Version, Commit, Built date, Go version)
- `format=json` (default): structured JSON `{"version": "1.0.0", "commit": "abc1234", "built": "...", "go_version": "go1.26.1"}`

## Readiness Check

```http
GET /api/ready
```

**Responses:**

- Normal operation: `{"ready":true}` (HTTP 200)
- During shutdown: `{"ready":false}` (HTTP 503 Service Unavailable)

**Purpose:** Indicates whether the server is ready to accept new requests. Returns false during graceful shutdown to allow existing requests to complete while preventing new ones.

## Greet Service v1

```http
GET /api/v1/greet/
GET /api/v1/greet/{name}
```

**Examples:**

```bash
# Default greeting
curl http://localhost:8080/api/v1/greet/
# Response: {"message":"Hello world!"}

# Personalized greeting
curl http://localhost:8080/api/v1/greet/John
# Response: {"message":"Hello John!"}

# Another example
curl http://localhost:8080/api/v1/greet/Alice
# Response: {"message":"Hello Alice!"}
```

## Greet Service v2 (Feature-flagged)

```http
POST /api/v2/greet
```

**Request Body:**

```json
{
  "name": "John"
}
```

**Examples:**

```bash
# Valid request
curl -X POST http://localhost:8080/api/v2/greet \
  -H "Content-Type: application/json" \
  -d '{"name":"John"}'
# Response: {"message":"Hello my friend John!"}

# Empty name (valid, returns default)
curl -X POST http://localhost:8080/api/v2/greet \
  -H "Content-Type: application/json" \
  -d '{"name":""}'
# Response: {"message":"Hello my friend!"}

# Missing name field (valid, returns default)
curl -X POST http://localhost:8080/api/v2/greet \
  -H "Content-Type: application/json" \
  -d '{}'
# Response: {"message":"Hello my friend!"}

# Name too long (validation error)
curl -X POST http://localhost:8080/api/v2/greet \
  -H "Content-Type: application/json" \
  -d '{"name":"ThisNameIsWayTooLongAndShouldFailValidationBecauseItExceedsTheMaximumAllowedLengthOf100Characters!!!!"}'
# Response: {"error":"validation_failed","message":"Invalid request data","details":[{"message":"Name failed validation for 'max' (parameter: 100)"}]}
```

**Validation Rules:**

- `name`: Maximum length 100 characters (optional field)

**Feature Flag:** Enable with `DLC_API_V2_ENABLED=true` or in config file with `api.v2_enabled: true`.