Kupon servisi, sipariş servisi ve bildirim servisi birbirini API (application programming interface) üzerinden çağırır. Sözleşmeyi (contract) geliştirici yazar, sen okursun: yazdığın kural sözleşmede bir yere oturuyor mu? Bu tarayıcıda gerçek bir servis çalışmıyor; bu ders okumaya ve çıkan veriyi SQL ile doğrulamaya dayanır.
REST'in dört fiili
| Fiil (verb) | Ne yapar? | Kupon örneği |
|---|---|---|
GET | Okur, hiçbir şey değiştirmez | GET /musteriler/162/kuponlar |
POST | Yeni kayıt ya da işlem başlatır | POST /kuponlar |
PUT / PATCH | Günceller (tamamını / bir kısmını) | PATCH /kuponlar/88 ile kullanım zamanı |
DELETE | Siler ya da pasifleştirir | DELETE /kuponlar/88 |
İstek ve cevap
JSON, anahtar-değer çiftlerinden oluşan metin biçimidir. Aşağıdaki sözleşme parçasını oku:
POST /kuponlar
Idempotency-Key: siparis-5045
{
"order_id": 5045,
"neden": "gec_teslim"
}
201 Created
{
"kupon_id": 88,
"order_id": 5045,
"customer_id": 162,
"tutar": 30.00,
"para_birimi": "TRY",
"son_kullanim": "2025-01-07T14:01:48+03:00"
}
Okurken soracakların: Tutarı kim hesaplıyor, çağıran mı, servis mi? (Burada servis; iyi, kural tek yerde kalır.) Saat dilimi yazıyor mu? (Evet, +03:00.) Tutar sayı mı, metin mi? son_kullanim bir iş kuralı getirdi: 30 gün mü, bu BRD'de yazıyor mu?
Durum kodları
| Kod | Anlamı | Kuponda ne zaman? |
|---|---|---|
200 OK | İstek başarılı | Aynı istek ikinci kez geldi, mevcut kupon döndü |
201 Created | Yeni kayıt oluştu | Kupon ilk kez üretildi |
400 Bad Request | İstek biçimi bozuk | order_id metin geldi |
401 / 403 | Kimlik yok / yetki yok | Çağıran servisin izni yok |
404 Not Found | Kayıt yok | Böyle bir sipariş yok |
409 Conflict | Mevcut durumla çakışıyor | Aynı siparişe farklı anahtarla ikinci kupon |
422 Unprocessable Content | Biçim doğru, iş kuralı uymuyor | Sipariş iptal, kupon verilemez |
500 / 503 | Sunucu tarafı hata | Veritabanı yanıt vermedi; yeniden denenebilir |
Sınır çizgisi ekipten ekibe değişir: bazı ekipler iş kuralı ihlalini 400 ile döner. Önemli olan her hata senaryosunun sözleşmede yazılı olması ve aynı anlamda kullanılmasıdır.
Idempotency
Ağ kopar, çağıran taraf cevabı alamadığı için isteği tekrarlar. Servis ikinci kupon üretirse şirket para kaybeder. Idempotent işlem, kaç kez çalışırsa çalışsın sonucu aynı olan işlemdir. GET doğası gereği böyledir; POST için özel önlem gerekir: Idempotency-Key başlığı ya da tablodaki UNIQUE kısıtı. Gereksinim cümlesi: “Aynı sipariş için tekrarlanan istek yeni kupon üretmez, ilk kuponu döner.”
Hata durumları tablosu
| Durum | Çağıran ne yapar? | Müşteri ne görür? |
|---|---|---|
| Kupon servisi 5 saniyede cevap vermedi | En çok 3 kez yeniden dener | Hiçbir şey; kupon sonra gelir |
3 denemede de 500 | Kaydı hata kuyruğuna yazar | Operasyon inceler, sonra kupon gelir |
422 (kural dışı) | Yeniden denemez, loglar | Kupon yok |
Yeniden denenecek ve denenmeyecek hataları ayırmak iş kararıdır. Sayıları (3 deneme, 5 saniye) burada önerdik, senin projende ekip belirler.
API'yi tablolara eşle
| API alanı | Tablo ve sütun | Not |
|---|---|---|
order_id | lk_orders.order_id | İstekle gelir, varlığı kontrol edilir |
customer_id | lk_orders.customer_id | İstekle gelmez, siparişten bulunur |
tutar | hesaplanır, ba_kupon.tutar | Karar tablosundan |
son_kullanim | kaynak yok | Açık soru: tabloda alan yok, süre için karar gerekli (Canlıya geçiş dersindeki mini BRD bunu 30 gün olarak kapatır) |
Son satır sözleşmeyi okumanın kazancıdır: API'de olan alanın tabloda karşılığı yok. Bunu geliştirme başlamadan yakalamak ucuzdur. Gerçek API'lerle Python'dan çalışmak istersen Kesit Python'daki BT İş Analisti yolunda HTTP dersi var.