first commit

2026-02-28 02:44:41 +03:00
commit 97fb289fe7
70 changed files with 11928 additions and 0 deletions
--- a/doc/api.md
+++ b/doc/api.md
@@ -0,0 +1,256 @@
+# 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)