Skip to content

API_SUMMARY.md

Latest commit

 

History

History
116 lines (92 loc) · 2.7 KB

API_SUMMARY.md

File metadata and controls

116 lines (92 loc) · 2.7 KB

Interview AI Server - API Quick Reference

🎯 Endpoint Özeti

Method Endpoint Açıklama Durum
GET /health Sunucu durumu ✅ Aktif
POST /api/interview-record Analiz başlat ✅ Aktif
GET /api/job-result/:videoResponseId Sonuç getir (video ID) ✅ Aktif
GET /api/job-result/by-job/:jobId Sonuç getir (pipeline ID) ✅ Aktif

📤 Analiz Başlatma

Endpoint: POST /api/interview-record

Minimum Gerekli Alan:

{
  "meta": { "apiVersion": "1.0.0", "requestId": "...", "timestamp": "..." },
  "application": { "id": "...", "candidate": { "name": "...", "surname": "...", "email": "..." } },
  "interview": {
    "id": "...",
    "position": { "id": "...", "title": "...", "competencyWeights": {...} },
    "questions": [
      {
        "id": "...",
        "questionText": "...",
        "video": { "videoResponseId": "...", "url": "https://..." }
      }
    ]
  }
}

Response:

{
  "ok": true,
  "interviewRecordId": "674a8f...",
  "pipelines": [{ "questionId": "q1", "pipelineId": "674a8f..." }]
}

📥 Sonuç Sorgulama

Endpoint: GET /api/job-result/:videoResponseId

Response (Tamamlandığında):

{
  "status": "success",
  "result": {
    "transcription": { "text": "...", "duration": 120 },
    "faceScores": { "confidence": 85, "engagement": 78, "eye_contact": 72 },
    "voiceScores": { "clarity": 88, "confidence": 80, "speech_rate": 145 },
    "evaluationResult": { "overallScore": 82, "feedback": "..." }
  }
}

404 Response (Henüz hazır değilse):

{
  "status": "not_found",
  "message": "Sonuç bulunamadı."
}

⏱️ Süreç Akışı

1. POST /api/interview-record
   ↓ (Instant response)
2. Kaydet: interviewRecordId, pipelineIds
   ↓ (2-5 dakika işlem süresi)
3. Polling başlat (30s interval)
   ↓
4. GET /api/job-result/:videoResponseId
   ↓ (404 → devam, 200 → tamamlandı)
5. Sonucu al ve kendi DB'ye kaydet

🔧 Best Practices

✅ Yapılması Gerekenler:

  • 30 saniye polling interval
  • Unique requestId kullan
  • Video URL'lerin HTTP GET ile indirilebilir olduğunu doğrula
  • Timeout: 30 saniye
  • Retry: Exponential backoff (3x)

❌ Yapılmaması Gerekenler:

  • 5 saniyede bir polling
  • Video dosyası base64 gönderme
  • Sonsuz polling (max 40 deneme = 20 dakika)

📚 Detaylı Dokümantasyon

API Version: 1.0.0
Base URL: http://localhost:3000 (development)