Livrare LOT 1 - Didi

ai_platform/modules/catalog-api/API.md

@@ -0,0 +1,225 @@
+# Catalog API Documentation
+
+Service catalog and discovery API that aggregates component information from all ML services.
+
+## Base URL
+
+```
+{BASE_URL}
+```
+
+- **Docker (internal):** `http://didiAI-catalog-api:11000`
+- **Via gateway:** `http://<host>:11000/catalog/`
+
+## Authentication
+
+No authentication required on direct access. When accessed via the gateway, Bearer token authentication is enforced by nginx.
+
+---
+
+## Endpoints
+
+### Health Check
+
+```
+GET /health
+```
+
+**Response:**
+```json
+{
+  "status": "ok"
+}
+```
+
+---
+
+### List Components
+
+List all registered components with full metadata (resource info, models, functions).
+
+```
+GET /v1/components
+```
+
+**Response:**
+```json
+{
+  "components": [
+    {
+      "component_id": "llm-inference",
+      "base_url": "http://didiAI-llm-api:14011",
+      "resource": { "name": "LLM Inference Gateway", "slug": "llm-inference", ... },
+      "models": [...],
+      "functions": [...]
+    }
+  ],
+  "total": 4,
+  "errors": null
+}
+```
+
+---
+
+### Get Component
+
+Get metadata for a specific component by ID.
+
+```
+GET /v1/components/{component_id}
+```
+
+**Path Parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `component_id` | string | Component ID (e.g., `llm-inference`, `audio-transcription`, `video-analysis`, `web-factcheck`) |
+
+**Response:** Same structure as a single component from `/v1/components`.
+
+**Error (404):**
+```json
+{
+  "detail": "Component 'unknown' not found"
+}
+```
+
+---
+
+### List Models
+
+List all available models across all components.
+
+```
+GET /v1/models
+```
+
+**Response:**
+```json
+{
+  "models": [
+    {
+      "name": "Qwen3.5-35B-A3B",
+      "slug": "qwen3.5",
+      "provider": "vllm",
+      "model_type": "llm",
+      "component_id": "llm-inference",
+      "component_name": "LLM Inference Gateway"
+    }
+  ],
+  "total": 5
+}
+```
+
+---
+
+### List Functions
+
+List all available functions/endpoints across all components.
+
+```
+GET /v1/functions
+```
+
+**Response:**
+```json
+{
+  "functions": [
+    {
+      "name": "Chat Completions",
+      "slug": "chat-completions",
+      "method": "POST",
+      "path": "/v1/chat/completions",
+      "component_id": "llm-inference"
+    }
+  ],
+  "total": 10
+}
+```
+
+---
+
+### System Status
+
+Aggregated health status of all components.
+
+```
+GET /v1/status
+```
+
+**Response:**
+```json
+{
+  "status": "healthy",
+  "components": [
+    {
+      "component_id": "llm-inference",
+      "url": "http://didiAI-llm-api:14011",
+      "reachable": true,
+      "healthy": true,
+      "status_code": 200
+    }
+  ],
+  "healthy_count": 4,
+  "total_count": 4
+}
+```
+
+**Status values:** `healthy` (all ok), `degraded` (some ok), `unhealthy` (none ok).
+
+---
+
+### Aggregated OpenAPI Spec
+
+Combined OpenAPI 3.1.0 specification from all components.
+
+```
+GET /v1/openapi
+```
+
+**Response:** Full OpenAPI JSON spec with paths prefixed by `/{component_id}` and schemas prefixed by `{component_id}_`.
+
+---
+
+### Swagger UI
+
+Interactive API documentation (Swagger UI) for the aggregated spec.
+
+```
+GET /v1/docs
+```
+
+---
+
+### ReDoc
+
+Alternative API documentation (ReDoc) for the aggregated spec.
+
+```
+GET /v1/redoc
+```
+
+---
+
+### Component OpenAPI Spec
+
+Raw OpenAPI spec for a single component.
+
+```
+GET /v1/openapi/component/{component_id}
+```
+
+---
+
+## Error Responses
+
+| Code | Description |
+|------|-------------|
+| 404 | Component not found |
+| 500 | Internal error (component unreachable) |
+
+## Request Headers
+
+| Header | Required | Description |
+|--------|----------|-------------|
+| `Accept` | No | `application/json` (default) |