ministore-api

Crystal dili ile yazılmış küçük bir e-ticaret arka uç (backend) servisi. Ürün listeleme/süzme, sepet ve sipariş uçlarının yanında GitHub üzerinden OAuth 2.0 ile giriş içerir.

Bu proje, 2026 yaz dönemi zorunlu staj çalışması kapsamında öğrendiğim konuları (katmanlı yapı, REST uçları, süzme ve sayfalama, oturum yönetimi, birim testleri) tek bir küçük örnekte toplamak için yazıldı.

Neden Crystal?

Ruby'ye çok yakın, okunması kolay bir sözdizimi sunarken statik tiplidir ve yerel makine koduna derlenir. Yazarken betik dili rahatlığı, çalışırken derlenmiş dil hızı veriyor. Tüm proje standart kütüphane ile yazıldı; hiçbir dış paket bağımlılığı yok, shards install çalıştırmaya gerek kalmıyor.

Özellikler

• GitHub OAuth 2.0 yetkilendirme kodu akışı (CSRF'e karşı tek kullanımlık state değeri ile)
• HMAC-SHA256 ile imzalanmış, süreli oturum belirteçleri
• Ürün listeleme: kategori + fiyat aralığı süzme, sıralama, sayfalama
• Sepet ve sipariş uçları; sipariş oluşturulurken stok kontrolü ve stok düşme tek kilit altında
• Gelen verinin doğrulanması ve tutarlı hata gövdeleri ({"error": ..., "message": ...})
• 13 birim testi

Kurulum

git clone https://github.com/mustafa3rsan/ministore-api.git
cd ministore-api
cp .env.example .env      # değerleri doldurun

crystal run src/ministore.cr          # geliştirme
crystal build src/ministore.cr -o bin/ministore-api --release   # üretim derlemesi
crystal spec                          # testler

Ortam değişkenleri

Değişken	Açıklama
GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET	GitHub OAuth uygulama bilgileri
OAUTH_REDIRECT_URI	Varsayılan: http://localhost:3000/auth/github/callback
APP_SECRET	Oturum belirteçlerinin imzalanma anahtarı
ALLOW_DEV_LOGIN	true ise GitHub olmadan deneme girişi açılır
PORT	Varsayılan: 3000

OAuth akışı

  tarayıcı                ministore-api                 github.com
     |                          |                            |
     |  GET /auth/github        |                            |
     |------------------------->|  state üret + sakla        |
     |   302 -> github.com/login/oauth/authorize ----------->|
     |                          |                            |
     |<--- 302 /auth/github/callback?code=..&state=.. -------|
     |------------------------->|  state doğrula             |
     |                          |  POST /login/oauth/access_token
     |                          |--------------------------->|
     |                          |<------- access_token ------|
     |                          |  GET /user  --------------->|
     |                          |<------- kullanıcı ---------|
     |<-- {"token": "...", "user": {...}} ------------------ |

Uç noktalar

Metot	Yol	Açıklama
GET	/health	Sağlık denetimi
GET	/auth/github	GitHub'a yönlendirir
GET	/auth/github/callback	Kodu belirteçle takas eder, oturum açar
POST	/auth/dev-login	Geliştirme girişi (yalnızca ALLOW_DEV_LOGIN=true iken)
GET	/api/me	Oturumdaki kullanıcı
GET	/api/products	category, min_price, max_price, sort, direction, page, per_page
GET	/api/products/:id	Ürün ayrıntısı
GET	/api/cart	Sepeti getirir
POST	/api/cart/items	Sepete ürün ekler
DELETE	/api/cart	Sepeti boşaltır
GET	/api/orders	Siparişleri listeler
POST	/api/orders	Sepetten sipariş oluşturur

Yetki gerektiren uçlar Authorization: Bearer <token> başlığı bekler.

Örnek kullanım

# ürünleri süz ve sırala
curl "http://localhost:3000/api/products?category=kitap&sort=price&direction=desc"

# geliştirme girişi ile belirteç al
TOKEN=$(curl -s -X POST http://localhost:3000/auth/dev-login \
        -d '{"login":"mustafa"}' | jq -r .token)

# sepete ekle ve sipariş oluştur
curl -X POST http://localhost:3000/api/cart/items \
     -H "Authorization: Bearer $TOKEN" \
     -H 'Content-Type: application/json' \
     -d '{"product_id": 2, "quantity": 2}'

curl -X POST http://localhost:3000/api/orders -H "Authorization: Bearer $TOKEN"

Proje yapısı

src/
  ministore.cr   # giriş noktası, sunucu ve ara katmanlar
  router.cr      # yönlendirme, doğrulama, hata gövdeleri
  store.cr       # bellek içi veri deposu (veri tabanı katmanının yerini tutar)
  models.cr      # Product, User, CartItem, Order
  auth.cr        # oturum belirteci üretme/doğrulama
  oauth.cr       # GitHub OAuth 2.0 akışı
spec/            # birim testleri

Bilinen sınırlar

Veriler bellekte tutulur, servis yeniden başladığında sıfırlanır. Amaç akışı göstermek olduğu için veri tabanı, ödeme ve kargo entegrasyonları kapsam dışı bırakıldı.

Lisans

MIT