REST API tam olarak ne yapar?
REST API, istemci ile veri ve iş kurallarını yöneten backend arasındaki sınırdır. Mobil uygulama veya web arayüzü “siparişi getir” ya da “servis kaydını onayla” isteği gönderir; API kimliği ve yetkiyi kontrol eder, iş kuralını çalıştırır ve öngörülebilir bir yanıt döndürür.
| HTTP yöntemi | Tipik amaç | Örnek kaynak işlemi |
|---|---|---|
| GET | Veri okumak | Sipariş listesini getir |
| POST | Yeni işlem başlatmak | Yeni sipariş oluştur |
| PUT / PATCH | Mevcut veriyi değiştirmek | Teslimat adresini güncelle |
| DELETE | Kaynağı silmek veya pasifleştirmek | Taslak kaydı kaldır |
REST API ile backend aynı şey değildir
Backend; veritabanı, iş kuralları, zamanlanmış işler, kuyruklar, dosya depolama ve entegrasyonlar dahil sunucu tarafının tamamıdır. REST API bu sistemin dışarıya açılan sözleşmesidir. Aynı backend mobil uygulamaya REST API, yönetim işlerine kuyruk ve başka servislere olay mesajı sunabilir.
Güvenilir API için 6 temel karar
API kalitesini endpoint sayısı değil, davranışların tutarlılığı belirler. Aşağıdaki 6 karar geliştirme başlamadan yazılırsa mobil, web ve backend ekipleri aynı sözleşmeye göre ilerler.
| Karar | Yanıtlanacak soru | Beklenen çıktı |
|---|---|---|
| 1. Kaynak modeli | URL'ler hangi varlıkları temsil ediyor? | Tutarlı isim ve ilişki yapısı |
| 2. Doğrulama ve hata | Geçersiz istek nasıl açıklanıyor? | Alan bazlı, kararlı hata biçimi |
| 3. Kimlik ve yetki | Kim, hangi kaydı, hangi işlemi yapabilir? | Rol ve sahiplik matrisi |
| 4. Sürümleme | Kırıcı değişiklik nasıl yayınlanıyor? | Eski istemciyi koruyan geçiş planı |
| 5. Tekrar güvenliği | Aynı istek iki kez gelirse ne olur? | Çift ödeme veya çift kayıt engeli |
| 6. Gözlemlenebilirlik | Bir hata hangi istekten geldi? | İstek kimliği, log ve ölçüm |
Hata yanıtları neden sözleşmenin parçasıdır?
İstemci yalnız başarılı yanıtla çalışmaz. İnternet kesintisi, süresi dolan oturum, geçersiz alan, kota aşımı ve dış servis hatası kullanıcıya farklı biçimde anlatılmalıdır. Her endpoint farklı hata biçimi döndürürse arayüz kodu dallanır ve gerçek sorunlar genel bir “bir şeyler ters gitti” mesajına dönüşür.
- Her yanıtta izlenebilir bir istek kimliği kullanın.
- Kullanıcıya gösterilecek mesaj ile teknik log ayrıntısını ayırın.
- Alan doğrulama hatalarını ilgili alan adıyla döndürün.
- Kimlik doğrulama, yetki ve bulunamama durumlarını birbirine karıştırmayın.
- Dış servis hataları için zaman aşımı ve yeniden deneme sınırı belirleyin.
Güvenlik yalnız giriş ekranı değildir
API güvenliği her istekte kimlik, yetki, veri kapsamı ve hız sınırı kontrolü gerektirir. Kullanıcının giriş yapmış olması başka bir kullanıcının kaydını görebileceği anlamına gelmez. Kaynak sahipliği sunucuda doğrulanmalı; gizli anahtarlar mobil veya web istemcisine konmamalıdır.
API tesliminde hangi belgeler bulunmalı?
Teslim edilebilir bir API; çalışan kodun yanında makinece okunabilir endpoint tanımı, örnek istek ve yanıtlar, kimlik akışı, hata kataloğu ve yerel kurulum adımları içerir. Bu belgeler yeni bir geliştiricinin sözlü aktarım olmadan ilk isteği gönderebilmesini sağlamalıdır.