ratebubble/doc/api.md

Netflix Scraper API - API Dokümantasyonu

Base URL

Development: http://localhost:3000
Production: https://api.yourdomain.com

Authentication

Tüm API istekleri X-API-Key header'ı gerektirir.

X-API-Key: your-api-key-here

API Key Tipleri

Key	Kullanım
API_KEY_WEB	Web frontend
API_KEY_MOBILE	Mobil uygulama
API_KEY_ADMIN	Admin panel

---

Endpoints

POST /api/getinfo

Netflix URL'sinden içerik bilgisi getirir.

Request

POST /api/getinfo
Content-Type: application/json
X-API-Key: your-api-key

{
  "url": "https://www.netflix.com/tr/title/81616256"
}

Response (Success)

{
  "success": true,
  "data": {
    "title": "Hayata Röveşata Çeken Adam",
    "year": 2022,
    "plot": "Dünyaya karşı duyduğu öfke ve yaşadığı kederin katılaştırdığı huysuz bir emekli, yaşamına son vermeyi planlar. Ancak hayatına neşeli bir genç aile girince tüm planları suya düşer.",
    "genres": ["18+", "Komedi"],
    "cast": ["Tom Hanks", "Mariana Treviño", "Rachel Keller"],
    "backdrop": "https://occ-0-7335-3467.1.nflxso.net/dnm/api/v6/..."
  }
}

Response (Error)

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "errors": [
        {
          "field": "url",
          "message": "URL must be a valid Netflix title URL"
        }
      ]
    }
  }
}

Status Codes

Code	Açıklama
200	Başarılı
400	Geçersiz istek
401	API key eksik
403	Geçersiz API key
429	Rate limit aşıldı
500	Sunucu hatası

---

POST /api/getinfo/async

Asenkron scraping job'u oluşturur. Büyük ölçekli kullanım için uygundur.

Request

POST /api/getinfo/async
Content-Type: application/json
X-API-Key: your-api-key

{
  "url": "https://www.netflix.com/tr/title/81616256"
}

Response

{
  "success": true,
  "data": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "pending"
  }
}

Socket ile İzleme

Job durumunu Socket.IO ile izleyebilirsiniz:

socket.emit('job:subscribe', jobId);
socket.on('job:progress', (data) => console.log(data));
socket.on('job:completed', (data) => console.log(data));
socket.on('job:error', (data) => console.error(data));

---

GET /api/jobs/:jobId

Job durumunu sorgular.

Request

GET /api/jobs/550e8400-e29b-41d4-a716-446655440000
X-API-Key: your-api-key

Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://www.netflix.com/tr/title/81616256",
    "status": "completed",
    "progress": 100,
    "step": "completed",
    "result": {
      "title": "Hayata Röveşata Çeken Adam",
      "year": 2022,
      "plot": "...",
      "genres": ["18+", "Komedi"],
      "cast": ["Tom Hanks", "Mariana Treviño", "Rachel Keller"],
      "backdrop": "https://..."
    },
    "createdAt": "2025-02-27T10:00:00.000Z",
    "updatedAt": "2025-02-27T10:00:05.000Z"
  }
}

---

GET /health

Basit sağlık kontrolü.

Response

{
  "status": "ok",
  "timestamp": "2025-02-27T10:00:00.000Z",
  "uptime": 3600
}

---

GET /ready

Tüm bağımlılıkların hazır olup olmadığını kontrol eder.

Response

{
  "status": "ready",
  "timestamp": "2025-02-27T10:00:00.000Z",
  "checks": {
    "database": "healthy",
    "redis": "healthy"
  },
  "env": "production"
}

---

Error Codes

Code	Açıklama
MISSING_API_KEY	API key header'ı eksik
INVALID_API_KEY	Geçersiz API key
VALIDATION_ERROR	İstek parametreleri geçersiz
RATE_LIMIT_EXCEEDED	Genel rate limit aşıldı
SCRAPE_RATE_LIMIT_EXCEEDED	Scraping rate limit aşıldı
SCRAPE_ERROR	Netflix'ten veri çekilemedi
JOB_NOT_FOUND	Job bulunamadı
INTERNAL_ERROR	Beklenmeyen sunucu hatası

---

Rate Limiting

Genel Rate Limit

• Window: 1 dakika
• Max İstek: 30 istek/dakika/IP+APIKey

Scraping Rate Limit

• Window: 1 dakika
• Max İstek: 10 istek/dakika/IP+APIKey

Rate limit değerleri .env dosyasından yapılandırılabilir.

---

Request/Response Formatları

Content Data (GetInfoResponse)

Alan	Tip	Açıklama
title	string	İçerik başlığı
year	number | null	Yayın yılı
plot	string | null	Açıklama/özet
genres	string[]	Tür listesi
cast	string[]	Oyuncu listesi
backdrop	string | null	Arka plan görseli URL

---

OpenAPI / Swagger

OpenAPI spesifikasyonu için: /api/docs (yakında)