257 lines
4.7 KiB
Markdown
257 lines
4.7 KiB
Markdown
# 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)
|