Verb API Documentation

Genel Bakış

Verb API, MySQL veritabanından veri çekmek ve kelime çevirisi yapmak için tasarlanmış RESTful bir API'dir.

Özellikler

✅ Token tabanlı kimlik doğrulama
✅ Şifrelenmiş iletişim
✅ 3 uygulama desteği (Lingora, Storylang, Wordflow)
✅ Level'e göre kelime çekme
✅ Otomatik kelime çevirisi ve ekleme
✅ 10 dil desteği
✅ CRUD işlemleri

Base URL

http://localhost:3000/api

Desteklenen Diller

en tr de fr es ar az it pt ru

🔐 Kimlik Doğrulama

Tüm API endpoint'leri (health check hariç) kimlik doğrulama gerektirir.

Token Formatı

Token şu formatta olmalıdır:

apitoken_userid_istekid

Örnek:

app1_secret_token_12345_user123_req456

Header'da Token Gönderme

cURL

curl http://localhost:3000/api/words \
  -H "x-api-token: app1_secret_token_12345_user123_req456"

JavaScript (Fetch)

fetch('http://localhost:3000/api/words', {
  headers: {
    'x-api-token': 'app1_secret_token_12345_user123_req456'
  }
})
.then(response => response.json())
.then(data => console.log(data));

Doğrulama Süreci

Token ayrıştırılır: apitoken, userid, istekid
API token'a göre uygulama tespit edilir
userid_istekid şifrelenir
İlgili uygulamanın /verifyVerbApi endpoint'ine gönderilir
Uygulama result: success dönerse istek işlenir

Uygulama Token'ları

Uygulama	API Token	Port
Lingora	`app1_secret_token_12345`	3001
Storylang	`app2_secret_token_67890`	3002
Wordflow	`app3_secret_token_abcde`	3003

📡 API Endpoints

GET /api/health Public

Veritabanı bağlantı durumunu kontrol eder.

Response

{
  "status": "OK",
  "database": "Connected"
}

GET /api/:table Protected

Belirtilen tablodan tüm kayıtları getirir.

Query Parameters

Parametre	Tip	Açıklama
`limit`	number	Sonuç sayısı
`offset`	number	Sayfalama offset'i
`orderBy`	string	Sıralama kolonu
`order`	string	ASC veya DESC

Example Request

cURL

curl "http://localhost:3000/api/words?limit=10&orderBy=id&order=DESC" \
  -H "x-api-token: app1_secret_token_12345_user123_req456"

Response

{
  "success": true,
  "count": 10,
  "data": [...]
}

GET /api/:table/:id Protected

Belirtilen ID'ye sahip kaydı getirir.

Example Request

curl http://localhost:3000/api/words/1 \
  -H "x-api-token: app1_secret_token_12345_user123_req457"

POST /api/:table Protected

Yeni bir kayıt oluşturur.

Example Request

curl -X POST http://localhost:3000/api/words \
  -H "Content-Type: application/json" \
  -H "x-api-token: app1_secret_token_12345_user123_req458" \
  -d '{
    "verb": "hello",
    "verbLang": "en",
    "level": "A1"
  }'

PUT /api/:table/:id Protected

Mevcut bir kaydı günceller.

DELETE /api/:table/:id Protected

Bir kaydı siler.

📖 Words API

Kelime çekme, çeviri ve otomatik kelime ekleme özellikleri.

GET /api/words/level/:level Protected

Belirtilen seviyedeki kelimeleri getirir.

Path Parameters

Parametre	Açıklama
`:level`	A1, A2, B1, B2, C1, C2

Query Parameters

Parametre	Tip	Varsayılan	Açıklama
`limit`	number	10	Sonuç sayısı
`offset`	number	0	Sayfalama offset'i
`verbLang`	string	en	Kelimenin dili
`targetLang`	string	-	Hedef dil (çeviri formatında döner)

Example Request

cURL

curl "http://localhost:3000/api/words/level/A1?targetLang=tr&limit=10" \
  -H "x-api-token: app1_secret_token_12345_user123_req459"

Response

{
  "success": true,
  "count": 10,
  "data": [
    {
      "id": 1,
      "verb": "other",
      "verbLang": "en",
      "level": "A1",
      "source": {
        "word": "other",
        "language": "en"
      },
      "target": {
        "translation": "diğer",
        "pronunciation": "diğer",
        "language": "tr"
      }
    }
  ],
  "level": "A1",
  "sourceLang": "en",
  "targetLang": "tr"
}

GET /api/words/translate Protected

Kelime çevirisi ve telaffuz bilgisi getirir.

Query Parameters

Parametre	Tip	Zorunlu	Açıklama
`word`	string	✅	Çevrilecek kelime
`sourceLang`	string	❌	Kaynak dil (varsayılan: en)
`targetLang`	string	✅	Hedef dil
`level`	string	❌	Kelime seviyesi

Example Request

cURL

curl "http://localhost:3000/api/words/translate?word=hello&sourceLang=en&targetLang=tr" \
  -H "x-api-token: app1_secret_token_12345_user123_req460"

Response

{
  "success": true,
  "data": {
    "id": 1,
    "verb": "hello",
    "verbLang": "en",
    "level": "A1",
    "source": {
      "word": "hello",
      "language": "en"
    },
    "target": {
      "translation": "merhaba",
      "pronunciation": "merhaba",
      "language": "tr"
    }
  }
}

GET /api/words/languages Protected

Desteklenen dilleri listeler.

Response

{
  "success": true,
  "languages": ["en", "tr", "de", "fr", "es", "ar", "az", "it", "pt", "ru"],
  "count": 10
}

Otomatik Kelime Ekleme

Eğer bir kelime veritabanında yoksa ve word parametresi ile sorgu yapılırsa:

Middleware kelimeyi kontrol eder
Kelime yoksa çeviri servisi çağrılır
Tüm desteklenen dillere çeviri yapılır
Yeni kelime veritabanına eklenir
Eklenen kelime response'da döner

💡 Örnekler

Örnek 1: A1 Seviyesindeki Kelimeleri Türkçe Çevirisiyle Çekme

curl "http://localhost:3000/api/words/level/A1?targetLang=tr&limit=10" \
  -H "x-api-token: app1_secret_token_12345_user123_req461"

Örnek 2: Yeni Kelime Ekleme ve Çeviri

curl "http://localhost:3000/api/words?word=wonderful&sourceLang=en&targetLang=tr&level=A2" \
  -H "x-api-token: app1_secret_token_12345_user123_req462"

Örnek 3: JavaScript ile Kelime Çekme

JavaScript

async function getWordsByLevel(level, targetLang) {
  const response = await fetch(
    `http://localhost:3000/api/words/level/${level}?targetLang=${targetLang}`,
    {
      headers: {
        'x-api-token': 'app1_secret_token_12345_user123_req463'
      }
    }
  );
  
  const data = await response.json();
  return data;
}

// Kullanım
getWordsByLevel('A1', 'tr').then(words => {
  console.log(words);
});

❌ Hata Kodları

401 Unauthorized

Token eksik veya geçersiz.

{
  "success": false,
  "error": "API token is required"
}

403 Forbidden

Uygulama doğrulaması başarısız.

{
  "success": false,
  "error": "Verification failed"
}

404 Not Found

Kayıt bulunamadı.

{
  "success": false,
  "message": "Record not found"
}

500 Internal Server Error

Sunucu hatası.

{
  "success": false,
  "error": "Error message"
}