174 lines
8.7 KiB
Markdown
174 lines
8.7 KiB
Markdown
# 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:**
|
||
```http
|
||
GET /api/books/isbn/9789750719383?locales=en,tr&withGemini=true HTTP/1.1
|
||
Host: localhost:8080
|
||
```
|
||
- **Ornek Donus:**
|
||
```json
|
||
{
|
||
"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:**
|
||
```http
|
||
GET /api/books/title?title=atomic%20habits&limit=2&locales=en HTTP/1.1
|
||
Host: localhost:8080
|
||
```
|
||
- **Ornek Donus:**
|
||
```json
|
||
{
|
||
"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:**
|
||
```http
|
||
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.
|