Gabriel Radureau
acebea353b
Endpoint introduced in PR #16 (commit c17fb4f) was missing from our
restructured documentation/API.md. Catching up before merging origin/main
into this feature branch.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
159 lines
4.1 KiB
Markdown
159 lines
4.1 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"}
|
|
```
|
|
|
|
## 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`.
|