# 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.

```http
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**

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

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

**Response (Success)**

```json
{
  "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)**

```json
{
  "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**

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

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

**Response**

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

**Socket ile İzleme**

Job durumunu Socket.IO ile izleyebilirsiniz:

```javascript
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**

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

**Response**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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)