dance-lessons-coach/documentation/API.md

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 with the command:

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

GET /api/health

Response:

{"status":"healthy"}

Version Info

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

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

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

Examples:

# 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)

POST /api/v2/greet

Request Body:

{
  "name": "John"
}

Examples:

# 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.