API Referencia¶

Overené podľa implementácie dňa 2026-05-07.

Zdroj pravdy pre kontrakt¶

1. src/app/api/*
2. src/app/schemas/*
3. runtime GET /openapi.json (v development/debug režime)
4. error kontrakty v src/app/api/contracts.py

Dôležité upresnenie¶

GitPulse nepoužíva JWT login endpoint typu /api/v1/auth/login.

Autentifikácia je riešená troma režimami:

1. Dashboard: GitLab OAuth + session cookie.
2. API: statický bearer token (TEACHER_API_TOKEN) alebo dashboard session.
3. Webhook endpoint: X-Gitlab-Token.

Základné prefixy¶

Health a ops endpointy¶

• GET /health
• GET /health/live
• GET /health/ready
• GET /metrics

Príklad:

1
2

curl http://localhost:8000/health
curl http://localhost:8000/metrics

API autentifikácia - príklady¶

Bearer token¶

1
2

curl http://localhost:8000/api/v1/courses/ \
  -H "Authorization: Bearer ${TEACHER_API_TOKEN}"

Webhook endpoint¶

1
2
3
4

curl -X POST http://localhost:8000/api/v1/webhooks/gitlab \
  -H "X-Gitlab-Token: ${WEBHOOK_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{"object_kind":"push"}'

Endpoint inventory (zgrupované)¶

Celkový scan: 200+ route handlerov.

Core API¶

• Kurzy: /api/v1/courses/*
• Tímy: /api/v1/teams/*
• Študenti: /api/v1/students/*
• Projekty: /api/v1/projects/*
• Používatelia: /api/v1/users/*

Event pipeline¶

• Webhook ingest: POST /api/v1/webhooks/gitlab
• DLQ/replay: /api/v1/events/*

Synchronizácia a joby¶

• Sync: /api/v1/teams/{team_id}/sync, /api/v1/courses/{course_id}/sync-all
• Recheck: /api/v1/teams/{team_id}/recheck - okamžité prepočítanie metrik (force all checks)
• Job status/SSE: /api/v1/jobs/{job_id}, /api/v1/jobs/{job_id}/stream

Hodnotenie¶

• Rubrics: /api/v1/courses/{course_id}/rubrics, /api/v1/rubrics/{rubric_id}/*
• Reporty: /api/v1/teams/{team_id}/report, /api/v1/reports/{filename}

Rozšírenia¶

• LLM: /api/v1/llm/mr/{project_id}/{mr_iid}
• Docker verify: /api/v1/docker-verify/report
• GitLab parse: /api/v1/gitlab/parse-url

Telemetria¶

• /api/v1/telemetry/* (activity, flags, compliance snapshots, feedback, report preview)

Dashboard routy¶

/dashboard/* obsahuje:

• login/logout/OAuth callback
• dashboard pre kurzy, tímy, študentov, projekty
• rubric UI
• admin sekcie (users, courses, system, events)

Mermaid mapa API domén¶

flowchart TB
    API["/api/v1"]
    API --> C["Courses"]
    API --> T["Teams"]
    API --> S["Students"]
    API --> P["Projects"]
    API --> U["Users"]
    API --> E["Events/Webhooks"]
    API --> R["Rubrics"]
    API --> SY["Sync + Jobs"]
    API --> TE["Telemetry"]
    API --> X["LLM / Docker Verify / GitLab Parse"]

OpenAPI export¶

1

curl http://localhost:8000/openapi.json > openapi.json

Poznámka: openapi.json, /docs, /redoc sú dostupné v development/debug režime.

Súvisiace dokumenty¶

• Architektúra
• GitLab webhooky
• Monitoring
• Detailný route inventory: docs/04-api-spec.md