bookibra/doc/api.md

Bookibra API Dokumani

Genel Bakis

Bookibra, Amazon kaynakli kitap verilerini ISBN, kitap adi ve yayin tarihi filtreleri ile sunan bir backend servisidir. Servis, gemini tabanli aciklama uretimi, Socket.IO altyapisi ve Redis/PostgreSQL baglanti noktalarini Docker uzerinden hazir halde getirir. ISBN tabanli tum sorgular otomatik olarak Redis uzerinde cache'lenir ve tekrar eden istekler Amazon'a gitmeden hizlica cevaplanir.

Calistirma

1. .env dosyanizi olusturun veya mevcut dosyada gerekli alanlari doldurun. Ornek icin .env.example goz atabilirsiniz. ISBN_CACHE_TTL_SECONDS degiskeni ile Redis cache omrunu saniye cinsinden ayarlayabilirsiniz (varsayilan 21600 sn / 6 saat). JWT tabanli oturum icin JWT_SECRET ve JWT_EXPIRES_IN alanlarini doldurun.
2. Docker ortamini acmak icin proje kok dizininde docker compose up --build komutunu calistirin.
3. API varsayilan olarak http://localhost:8080, React frontend ise http://localhost:5173 adresinde yayin yapar.

Not: Docker ortamina eklenen Redis (6379) ve PostgreSQL (5432) servisleri su anda veri saklama icin zorunlu degildir, ancak ileride kullanima hazir sekilde ayaga kalkar. Socket.IO, backend konteyneri icinde hazirlanmistir ve istemci baglantilarini kabul eder.

Ortak Parametreler

Her endpoint icin asagidaki sorgu parametreleri desteklenir:

Parametre	Tip	Varsayilan	Aciklama
locales	string	en,tr	en, tr veya en,tr seklinde virgulle ayrilmis diller. Her dil icin ayri Amazon kaynagi kullanilir.
withGemini	boolean	false	true oldugunda GEMINI_API_KEY kullanilarak kitap aciklamasi Gemini ile yeniden uretilir.
limit	integer	3	Liste bazli aramalarda donulecek maksimum kayit sayisi. ISBN aramasinda dikkate alinmaz.

withGemini=true parametresi kullanilirsa .env icinde GEMINI_API_KEY tanimli olmalidir, aksi halde API 400 hatasi dondurur.

Standart Yanıt Alanları

• cacheHit: (boolean) Yalnızca ISBN endpointinde görünür. Yanıt Redis'ten geldiyse true olur.
• normalizedIsbn: (string) Arama yaparken Amazon'a gönderilen normalize edilmis ISBN (ör: 605842285X -> 9786058422854). Kullanıcı girişi isbn alanında korunur.
• cachedThumbnail: (string) Thumbnail görselinin proje kokundaki cache/ dizininde saklanan göreli yolu. Frontend bu yolu kullanarak yereldeki görseli isteyebilir.
• cachedAt: (ISO tarih) Cache'e kaydedildiği zamanı gösterir. Cache'ten dönülen yanıtta da aynı değer gönderilir.

Kimlik Dogrulama Endpointleri

0. Kullanici Kaydi

• URL: POST /api/auth/register
• Body: { "email": "user@example.com", "password": "enAz6Karakter" }
• Donus: { "token": "<JWT>", "user": { "id": "...", "email": "..." } }

0.1 Giris

• URL: POST /api/auth/login
• Body: Kayit endpointi ile ayni.
• Donus: Basarili olursa JWT ve temel kullanici bilgileri.

0.2 Profil

• URL: GET /api/auth/profile
• Header: Authorization: Bearer <JWT>
• Donus: { "user": { "id": "...", "email": "..." } }

Not: Tum JWT'ler .env icindeki JWT_SECRET ile uretilir. Varsayilan sure JWT_EXPIRES_IN degiskeniyle (or. 1h, 2d) belirlenir.

Endpointler

1. ISBN ile Arama

• URL: GET /api/books/isbn/:isbn
• Aciklama: Verilen ISBN numarasi icin ingilizce (amazon.com) ve turkce (amazon.com.tr) kayitlarindan detaya ulasir. Ilk sorgu Amazon'dan alinip Redis'e kaydedilir; takip eden ayni parametreli sorgular cache'ten servis edilir.
• Ornek Istek:

  GET /api/books/isbn/9789750719383?locales=en,tr&withGemini=true HTTP/1.1
  Host: localhost:8080
  

• Ornek Donus:

  {
    "isbn": "9789750719383",
    "locales": ["en", "tr"],
    "includeGemini": true,
    "cacheHit": false,
    "cachedAt": "2024-01-10T12:34:56.789Z",
    "data": {
      "en": {
        "title": "Book Title",
        "authorName": "Author",
        "description": "Gemini tarafindan iyilestirilmis aciklama",
        "date": "September 5, 2023",
        "publisher": "Publisher",
        "rate": "4.7",
        "thumbImage": "https://..."
      },
      "tr": {
        "title": "Kitap Basligi",
        "description": "Gemini aciklamasi",
        "date": "5 Eylul 2023",
        "publisher": "Yayinevi"
      }
    }
  }
  

• Hata Durumlari:
  • 400: ISBN formati hatali veya Gemini anahtari eksik.
  • 404: Amazon tarafinda kayit bulunamazsa ilgili dil icin error alaninda bilgi gelir.

2. Kitap Adi ile Arama

• URL: GET /api/books/title
• Gerekli Parametre: title
• Aciklama: Amazon arama sayfalarindan belirlenen limit kadar kaydi bulur, her biri icin detay sayfasina giderek bilgileri toplar. Bu endpointte cache mekanizması devrede değildir.
• Ornek Istek:

  GET /api/books/title?title=atomic%20habits&limit=2&locales=en HTTP/1.1
  Host: localhost:8080
  

• Ornek Donus:

  {
    "title": "atomic habits",
    "locales": ["en"],
    "limit": 2,
    "includeGemini": false,
    "data": [
      {
        "locale": "en",
        "items": [
          {
            "asin": "0593189647",
            "locale": "en",
            "title": "Atomic Habits",
            "authorName": "James Clear",
            "date": "October 16, 2018",
            "publisher": "Avery",
            "rate": "4.8",
            "summary": {
              "asin": "0593189647",
              "title": "Atomic Habits",
              "price": "$16.20",
              "image": "https://...",
              "author": "James Clear"
            }
          }
        ]
      }
    ]
  }
  

3. Kitap Adi + Tarih Filtreli Arama

• URL: GET /api/books/filter
• Gerekli Parametreler: title, published
• Aciklama: Ilgili kitabi basliktan arar, donen kayitlari published degerini icerenler ile sinirlar. published alanina yil (2020) veya tam tarih (2020-05-01, May 2020, Eylul 2020) verilebilir. Bu endpointte de cache mekanizması devre dışıdır.
• Ornek Istek:

  GET /api/books/filter?title=lord%20of%20the%20rings&published=1954&locales=en,tr HTTP/1.1
  Host: localhost:8080
  

• Ornek Donus: title endpointi ile ayni yapida olur ancak items listesi sadece published bilgisini iceren kayitlari tutar.

Health Check

• URL: GET /health
• Aciklama: Servisin ayakta oldugunu dogrulamak icin kullanilir.

Socket.IO

• Sunucu baglantilarini kabul eder ve connection:ack etkinligi ile basit bir karsilama mesaji gonderir.
• Ileride frontend istemcileri bu kanal uzerinden bildirim alabilir.

Redis & Thumbnail Cache ve Loglama

• ISBN sorgulari book:isbn:{ISBN}:loc={lokaller}:gem={flag} formundaki anahtarlarla varsayilan olarak 6 saat (21600 sn) boyunca Redis'te saklanir. Sure .env icindeki ISBN_CACHE_TTL_SECONDS degiskeniyle degistirilebilir. Yeni bir sorgu cache olusturdukten sonra tum parametre uyumlu talepler direk Redis'ten 3xx/4xx/5xx durumlarina bakilmaksizin cevaplanir.
• Amazon'dan donen her thumbImage url'si indirilip proje kokundaki cache/ klasorune {isbn}_{locale}_thumbnail.jpg/png formatinda kaydedilir. Aynı istek tekrarlandiginda yerel dosya kullanilir ve API yanitina cachedThumbnail alanı olarak eklenir. Frontend bu yolu kullanarak dosyayi servis edebilir.
• Docker konsolunda 🚀, 📦 gibi emojili ve chalk tabanli renkli loglar gorunur. Her istegin suresi parantez icinde gosterilir (ornegin (152.3ms)), cache'den gelen yanitlarda [cache-hit 📦], Amazon'a gidilenlerde [cache-miss 🆕] etiketi yer alir.
• Redis veya thumbnail indirme surecinde olusan uyari/hata mesajlari da renklendirilmis bicimde loglanir; boylece sistem sagligi anlik olarak izlenebilir.

Frontend (React)

• frontend/ dizininde Vite + React 18 tabanli bir login ekranı bulunur. Google/Apple sosyal butonlari ve Booklibra baykus logosu ile uyumlu pastel renk paleti kullanir.
• Varsayilan olarak tarayicinin bulundugu hostname uzerinden :8080 portuna istek atar. Farkli bir domain kullanacaksaniz VITE_API_BASE_URL degiskenini http(s)://... formatinda build aninda girin.
• Gelistirme icin cd frontend && npm run dev -- --host komutu ile uygulamayi baslatabilirsiniz.

Altyapi

• Redis: redis://redis:6379 adresinde, docker-compose ile otomatik calisir.
• PostgreSQL: Varsayilan bookibra veritabani ve kullanicisi ile ayaga kalkar.
• Gemini: .env dosyasina GEMINI_API_KEY eklendiginde aciklama zenginlestirme ozelligi aktive olur.

Hata Mesajlari

• Tum hatalar JSON formatinda message ve code alanlariyla dondurulur.
• Uygulama NODE_ENV=development iken stack bilgisi eklenir.

Gelistirme Ipuclari

• Lokal gelistirme icin npm run dev komutu Socket.IO ve API'yi hot-reload modunda calistirir.
• Test yazmadiginiz sürece npm test komutu sadece bos bir mesaj basar ancak CI hataya dusmez.