api key and security
This commit is contained in:
salvacybersec
413
API.md
Normal file
413
API.md
Normal file
@@ -0,0 +1,413 @@
|
||||
# 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 video sayısı (varsayılan: 50, max: 500) |
|
||||
|
||||
\* `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=100"
|
||||
|
||||
# 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 video sayısı (varsayılan: 50)"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**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 video sayısı (varsayılan: 50)"
|
||||
},
|
||||
"examples": [
|
||||
"/?channel_id=UC9h8BDcXwkhZtnqoQJ7PggA&format=Atom",
|
||||
"/?channel=@tavakfi&format=Rss",
|
||||
"/?channel_url=https://www.youtube.com/@tavakfi&format=Atom&max_items=100"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**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: 500
|
||||
- Varsayılan: 50
|
||||
|
||||
## 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=10"
|
||||
```
|
||||
|
||||
## 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 arka planda asenkron olarak işlenir. 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.
|
||||
|
||||
## Destek
|
||||
|
||||
Sorularınız için GitHub Issues kullanabilirsiniz.
|
||||
|
||||
Reference in New Issue
Block a user