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

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

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