Gabriel Radureau
41ee8c56ac
Création de 9 fichiers neufs pour décharger AGENTS.md (1296 lignes →
~130) en documents lazy-loadables, compatibles avec la limite de
contexte 128k de Mistral Vibe (cf. ARCODANGE migration Phase 1,
Tâche 6 du curriculum).
Sept guides ciblés sous documentation/ :
- HISTORY.md : phases historiques 1-9 du développement
- CLI.md : commandes CLI, server lifecycle, config DLC_*
- API.md : endpoints REST, OpenAPI, Greet v1/v2
- OBSERVABILITY.md : OpenTelemetry + Jaeger, sampler types, test
- TROUBLESHOOTING.md : issues connues + pointeurs vers guides spé
- CODE_EXAMPLES.md : snippets endpoint/logging/context, pointeurs ADR
- ROADMAP.md : potential features, architectural improvements
Deux fichiers racine :
- CHANGELOG.md : user-facing, format Keep a Changelog
- AGENT_CHANGELOG.md : décisions structurantes des agents AI
(référencé par AGENTS.md, n'existait pas)
Le contenu est extrait fidèlement d'AGENTS.md sans réinterprétation.
Phase C (réécriture AGENTS.md court) suit dans le commit suivant.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
144 lines
3.6 KiB
Markdown
144 lines
3.6 KiB
Markdown
# 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"}
|
|
```
|
|
|
|
## 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`.
|