Youtube2Feed/API.md

# API Dokümantasyonu

YouTube Transcript RSS Feed API'si, YouTube kanallarının video transcript'lerini RSS/Atom feed formatında sunar.

## Base URL

```
http://localhost:5000
```

Production için base URL değişebilir.

## Authentication

**Tüm endpoint'ler API key gerektirir.**

API key'i iki şekilde gönderebilirsiniz:

### 1. HTTP Header (Önerilen)

```http
X-API-Key: your_api_key_here
```

### 2. Query Parameter

```
?api_key=your_api_key_here
```

### API Key Alma

API key'ler `config/security.yaml` dosyasından yönetilir. Yeni bir API key eklemek için:

```yaml
security:
  api_keys:
    your_api_key_here:
      name: "Your API Key Name"
      rate_limit: 100  # Dakikada maksimum istek
      enabled: true
```

### Hata Yanıtları

**401 Unauthorized** - API key eksik veya geçersiz:
```json
{
  "error": "Geçersiz veya eksik API key",
  "message": "X-API-Key header veya api_key query parametresi gerekli"
}
```

**429 Too Many Requests** - Rate limit aşıldı:
```json
{
  "error": "Rate limit aşıldı",
  "message": "Dakikada 100 istek limiti",
  "retry_after": 60
}
```

## Rate Limiting

Her API key için dakikada maksimum istek sayısı tanımlanır. Rate limit bilgisi response header'ında döner:

```
X-RateLimit-Remaining: 45
```

Rate limit aşıldığında `429 Too Many Requests` hatası döner.

## Endpoints

### 1. RSS/Atom Feed Oluştur

YouTube kanalı için transcript feed'i oluşturur.

**Endpoint:** `GET /`

**Query Parameters:**

| Parametre | Tip | Zorunlu | Açıklama |
|-----------|-----|---------|----------|
| `api_key` | string | ✅ | API key (header ile de gönderilebilir) |
| `channel_id` | string | ⚠️* | YouTube Channel ID (UC ile başlar, 24 karakter) |
| `channel` | string | ⚠️* | Channel handle (@username veya username) |
| `channel_url` | string | ⚠️* | Full YouTube channel URL |
| `format` | string | ❌ | Feed formatı: `Atom` (varsayılan) veya `Rss` |
| `max_items` | integer | ❌ | Maksimum transcript sayısı (varsayılan: 10, max: 100, 20'şer batch'ler halinde işlenir) |

\* `channel_id`, `channel` veya `channel_url` parametrelerinden biri zorunludur.

**Örnek İstekler:**

```bash
# Channel ID ile
curl -H "X-API-Key: demo_key_12345" \
  "http://localhost:5000/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&format=Atom"

# Channel handle ile
curl -H "X-API-Key: demo_key_12345" \
  "http://localhost:5000/?channel=@tavakfi&format=Atom"

# Channel URL ile
curl -H "X-API-Key: demo_key_12345" \
  "http://localhost:5000/?channel_url=https://www.youtube.com/@tavakfi&format=Atom&max_items=50"

# Query parametresi ile API key
curl "http://localhost:5000/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&api_key=demo_key_12345&format=Rss"
```

**Başarılı Yanıt:**

**Atom Format:**
```xml
<?xml version='1.0' encoding='UTF-8'?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:lang="en">
  <id>UC9h8BDcXwkhZtnqoQJ7PggA</id>
  <title>YouTube Transcript Feed - UC9h8BDcXwkhZtnqoQJ7PggA</title>
  <updated>2025-01-13T00:30:36+00:00</updated>
  <link href="https://www.youtube.com/channel/UC9h8BDcXwkhZtnqoQJ7PggA"/>
  <entry>
    <id>r5KfWUv6wqQ</id>
    <title>Video Title</title>
    <content type="html">
      <p>Transcript content...</p>
    </content>
    <link href="https://www.youtube.com/watch?v=r5KfWUv6wqQ"/>
    <published>2025-01-06T14:13:57+00:00</published>
  </entry>
</feed>
```

**RSS Format:**
```xml
<?xml version='1.0' encoding='UTF-8'?>
<rss version="2.0" xmlns:content="http://purl.org/rss/1.0/modules/content/">
  <channel>
    <title>YouTube Transcript Feed - UC9h8BDcXwkhZtnqoQJ7PggA</title>
    <link>https://www.youtube.com/channel/UC9h8BDcXwkhZtnqoQJ7PggA</link>
    <item>
      <title>Video Title</title>
      <content:encoded><![CDATA[<p>Transcript content...</p>]]></content:encoded>
      <link>https://www.youtube.com/watch?v=r5KfWUv6wqQ</link>
      <pubDate>Mon, 06 Jan 2025 14:13:57 +0000</pubDate>
    </item>
  </channel>
</rss>
```

**Hata Yanıtları:**

**400 Bad Request** - Geçersiz parametreler:
```json
{
  "error": "Channel ID bulunamadı",
  "usage": {
    "channel_id": "UC... (YouTube Channel ID)",
    "channel": "@username veya username",
    "channel_url": "https://www.youtube.com/@username veya https://www.youtube.com/channel/UC...",
    "format": "Atom veya Rss (varsayılan: Atom)",
    "max_items": "Maksimum transcript sayısı (varsayılan: 10, maksimum: 100, 20'şer batch'ler halinde işlenir)"
  }
}
```

**400 Bad Request** - Geçersiz format:
```json
{
  "error": "Geçersiz channel_id formatı",
  "message": "Channel ID UC ile başlayan 24 karakter olmalı"
}
```

**404 Not Found** - Henüz işlenmiş video yok:
```json
{
  "error": "Henüz işlenmiş video yok",
  "channel_id": "UC9h8BDcXwkhZtnqoQJ7PggA",
  "message": "Lütfen birkaç dakika sonra tekrar deneyin"
}
```

**500 Internal Server Error** - Sunucu hatası:
```json
{
  "error": "RSS-Bridge hatası: ...",
  "channel_id": "UC9h8BDcXwkhZtnqoQJ7PggA"
}
```

---

### 2. Health Check

Servisin durumunu kontrol eder. **API key gerektirmez.**

**Endpoint:** `GET /health`

**Örnek İstek:**

```bash
curl "http://localhost:5000/health"
```

**Başarılı Yanıt:**

```json
{
  "status": "ok",
  "service": "YouTube Transcript RSS Feed"
}
```

**HTTP Status:** `200 OK`

---

### 3. API Bilgileri

API hakkında bilgi döner.

**Endpoint:** `GET /info`

**Örnek İstek:**

```bash
curl -H "X-API-Key: demo_key_12345" "http://localhost:5000/info"
```

**Başarılı Yanıt:**

```json
{
  "service": "YouTube Transcript RSS Feed Generator",
  "version": "1.0.0",
  "endpoints": {
    "/": "RSS Feed Generator",
    "/health": "Health Check",
    "/info": "API Info"
  },
  "usage": {
    "channel_id": "UC... (YouTube Channel ID)",
    "channel": "@username veya username",
    "channel_url": "Full YouTube channel URL",
    "format": "Atom veya Rss (varsayılan: Atom)",
    "max_items": "Maksimum transcript sayısı (varsayılan: 10, maksimum: 100, 20'şer batch'ler halinde işlenir)"
  },
  "examples": [
    "/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&format=Atom",
    "/?channel=@tavakfi&format=Rss",
    "/?channel_url=https://www.youtube.com/@tavakfi&format=Atom&max_items=50"
  ]
}
```

**HTTP Status:** `200 OK`

---

## Response Headers

Tüm başarılı response'larda aşağıdaki header'lar bulunur:

| Header | Açıklama |
|--------|----------|
| `X-RateLimit-Remaining` | Kalan istek sayısı |
| `X-Content-Type-Options` | `nosniff` |
| `X-Frame-Options` | `DENY` |
| `X-XSS-Protection` | `1; mode=block` |
| `Content-Type` | `application/atom+xml` veya `application/rss+xml` |

## Hata Kodları

| HTTP Status | Açıklama |
|-------------|----------|
| `200 OK` | İstek başarılı |
| `400 Bad Request` | Geçersiz parametreler |
| `401 Unauthorized` | API key eksik veya geçersiz |
| `404 Not Found` | Kaynak bulunamadı |
| `429 Too Many Requests` | Rate limit aşıldı |
| `500 Internal Server Error` | Sunucu hatası |

## Input Validation

### Channel ID Formatı

- `UC` ile başlamalı
- Toplam 24 karakter
- Alfanumerik karakterler + `_` ve `-`

**Örnek:** `UC9h8BDcXwkhZtnqoQJ7PggA`

### Channel Handle Formatı

- `@` ile başlayabilir veya başlamayabilir
- Maksimum 30 karakter
- Alfanumerik karakterler + `_` ve `-`

**Örnekler:** `@tavakfi`, `tavakfi`

### Channel URL Formatı

Sadece aşağıdaki formatlar kabul edilir:

- `https://www.youtube.com/channel/UC...`
- `https://www.youtube.com/@username`
- `https://youtube.com/channel/UC...`
- `https://youtube.com/@username`

### max_items

- Tip: Integer
- Minimum: 1
- Maksimum: 100
- Varsayılan: 10
- **Batch İşleme**: 20'şer batch'ler halinde işlenir (YouTube IP blocking önleme için)
- **Veritabanı Kaydı**: Her batch işlendikten sonra hemen veritabanına kaydedilir, böylece sonraki sorgularda görülebilir

## CORS

API CORS desteği sağlar. Preflight request'ler için `OPTIONS` metodu kullanılır.

**İzin Verilen Methodlar:** `GET`, `OPTIONS`

**İzin Verilen Header'lar:** `Content-Type`, `X-API-Key`

## Örnek Kullanım Senaryoları

### 1. RSS Reader ile Kullanım

RSS reader uygulamanızda feed URL'si olarak kullanın:

```
http://your-api.com/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&format=Rss&api_key=your_api_key
```

### 2. Programatik Kullanım (Python)

```python
import requests

api_key = "your_api_key_here"
channel_id = "UC9h8BDcXwkhZtnqoQJ7PggA"

headers = {
    "X-API-Key": api_key
}

response = requests.get(
    f"http://localhost:5000/?channel_id={channel_id}&format=Atom",
    headers=headers
)

if response.status_code == 200:
    feed_content = response.text
    print(feed_content)
else:
    print(f"Error: {response.status_code}")
    print(response.json())
```

### 3. Programatik Kullanım (JavaScript)

```javascript
const apiKey = "your_api_key_here";
const channelId = "UC9h8BDcXwkhZtnqoQJ7PggA";

fetch(`http://localhost:5000/?channel_id=${channelId}&format=Atom`, {
  headers: {
    "X-API-Key": apiKey
  }
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.text();
  })
  .then(feedContent => {
    console.log(feedContent);
  })
  .catch(error => {
    console.error("Error:", error);
  });
```

### 4. cURL ile Test

```bash
# API key ile test
API_KEY="demo_key_12345"
CHANNEL_ID="UC9h8BDcXwkhZtnqoQJ7PggA"

curl -H "X-API-Key: $API_KEY" \
  "http://localhost:5000/?channel_id=$CHANNEL_ID&format=Atom&max_items=50"
```

## Notlar

1. **İlk İstek**: İlk istekte transcript'ler henüz işlenmemiş olabilir. Birkaç dakika bekleyip tekrar deneyin.

2. **Rate Limiting**: Her API key için farklı rate limit tanımlanabilir. Limit aşıldığında 60 saniye beklemeniz gerekir.

3. **Transcript İşleme**: 
   - Transcript'ler 20'şer batch'ler halinde işlenir (YouTube IP blocking önleme için)
   - Her batch işlendikten sonra veritabanına kaydedilir
   - `max_items` parametresi ile her istekte işlenecek transcript sayısını kontrol edebilirsiniz (maksimum 100)
   - Batch'ler arası 2 saniye bekleme süresi vardır
   - Yeni videolar için birkaç dakika gecikme olabilir

4. **Format Seçimi**: Atom formatı daha modern ve önerilir. RSS formatı eski RSS reader'lar için uygundur.

5. **API Key Güvenliği**: API key'lerinizi güvenli tutun ve asla public repository'lere commit etmeyin.

6. **Batch İşleme Örneği**: 
   - `max_items=50` isteği: 20+20+10 batch'ler halinde işlenir
   - Her batch tamamlandığında veritabanına kaydedilir
   - Sonraki sorgularda tüm işlenmiş transcript'ler görülebilir

## Destek

Sorularınız için GitHub Issues kullanabilirsiniz.