API Girdi Doğrulama: Şema Kontrolü ve Sınır Değerler
API'niz bir sayı bekliyor ve istemci metin gönderdi. Uygulamanız hata verdi ama hata mesajı veritabanı katmanından geldi ve içinde tablo adları vardı. Hem çöktünüz hem iç yapınızı gösterdiniz.
Bu yazı, API girdilerini doğru doğrulamayı ele alıyor.
Doğrulama Nerede Yapılmalı?
| Katman | Rolü |
|---|---|
| İstemci tarafı | Yalnızca deneyim |
| API giriş noktası | Biçim ve tür kontrolü |
| İş mantığı | Kural kontrolü |
| Veritabanı | Son savunma |
Birinci satır asla güvenlik katmanı sayılmamalıdır: istemci tarafındaki doğrulama yalnızca kullanıcıya hızlı geri bildirim içindir — API'nize doğrudan istek gönderen biri o kontrolü tamamen atlar.
Bu, tarayıcı geliştirici araçlarıyla saniyeler içinde yapılabilir.
İkinci satır ise asıl kapıdır ve iş mantığına ulaşmadan önce filtrelemelidir.
Dördüncü satır ise bir güvenlik ağıdır ama tek başına yeterli değildir; oradan gelen hata mesajları kullanıcıya uygun değildir.
Şema Tabanlı Doğrulama
Alan alan kontrol yazmak yerine yapı tanımlanır:
- Zorunlu alanlar belirtilir.
- Her alanın türü tanımlanır.
- Sınır değerler yazılır.
- Fazladan alanlar reddedilir.
Dördüncü madde çok atlanan ama önemli bir güvenlik önlemidir: beklenmeyen alanları sessizce yok saymak yerine reddetmek, istemcinin gönderdiği bir "yetki" alanının kazara işlenmesini baştan engeller.
Bu, kütle atama açığının temel savunmasıdır.
Ayrıca istemci tarafındaki yazım hatalarını da yakalar; alan adı yanlış yazıldığında sessizce yok sayılmaz.
Üçüncü madde ise sınır durumlarını kapsar ve sonraki bölümün konusudur.
Sınır Değerler
- Metin uzunluğu üst sınırı.
- Sayı aralığı.
- Dizi eleman sayısı.
- İç içe derinlik.
Üçüncü madde bir hizmet engelleme vektörünü kapatır: bir dizi alanına sınır koymazsanız istemci yüz bin elemanlı bir liste gönderebilir ve uygulamanız her elemanı işlemeye çalışırken kaynakları tüketir.
Bu, tek bir istekle sunucuyu meşgul etmenin kolay yoludur.
Dördüncü madde ise ayrıştırma aşamasında sorun çıkarır. Çok derin iç içe geçmiş bir yapı, ayrıştırıcıyı yorabilir.
Birinci madde ise veritabanı alan sınırlarıyla uyumlu olmalıdır; aksi hâlde doğrulamayı geçen veri kaydedilirken hata verir.
Tür Dönüşümü Tuzakları
| Gelen değer | Risk |
|---|---|
| Metin olarak sayı | Sessiz dönüşüm |
| Boş metin | Sıfıra dönebilir |
| Null değer | Eksik mi, kasıtlı mı? |
| Ondalık ayırıcı | Bölgesel fark |
Üçüncü satır çok önemli bir ayrımdır: bir alanın hiç gönderilmemesi ile boş olarak gönderilmesi farklı anlamlar taşır — biri "değiştirme" diğeri "temizle" demektir ve bunları karıştırmak veri kaybettirir.
Kısmi güncelleme yapan uç noktalarda bu ayrım kritiktir.
İkinci satır ise sessiz veri hatası üretir. Boş bir metnin sıfır olarak kaydedilmesi, fiyat alanında ciddi sonuç doğurur.
Dördüncü satır ise uluslararası istemcilerde yaşanır ve API'de tek bir biçim zorunlu tutulmalıdır.
Hata Yanıtı Tasarımı
- Tüm hataları birden döndürün.
- Alan bazında belirtin.
- Makine okunabilir kod verin.
- İç detay sızdırmayın.
Birinci madde istemci deneyimini belirgin biçimde iyileştirir: ilk hatada durup tek bir mesaj döndürmek, istemcinin formu defalarca göndermesine yol açar — tüm doğrulama hatalarını tek yanıtta vermek kullanıcının hepsini birden düzeltmesini sağlar.
Bu, form arayüzlerinde büyük fark yaratır.
Dördüncü madde ise başta anlatılan sızıntıyı önler. Veritabanı hata mesajları asla dışarıya verilmemelidir.
Üçüncü madde ise istemcinin hataya programatik tepki vermesini sağlar; metin mesajı çevrilebilir ama kod sabittir.
Doğru Durum Kodu
| Durum | Uygun kod |
|---|---|
| Bozuk gövde | 400 |
| Şema uyumsuzluğu | 400 veya 422 |
| İş kuralı ihlali | 422 |
| Çakışan durum | 409 |
Üçüncü satır ince ama yararlı bir ayrımdır: biçim olarak geçerli ama iş kuralına aykırı bir istek — örneğin bitiş tarihinin başlangıçtan önce olması — yapısal bir hata değildir ve farklı bir kodla bildirilmesi istemcinin doğru tepki vermesini sağlar.
Bu ayrım yapılmazsa istemci tüm hataları aynı şekilde ele alır.
Dördüncü satır ise eşzamanlılık durumlarında kullanılır; kayıt başkası tarafından değiştirilmiştir.
Tutarlılık en önemlisidir; aynı hata türü tüm uç noktalarda aynı kodu döndürmelidir.
Doğrulama ve Temizleme
- Doğrulama reddeder.
- Temizleme değiştirir.
- İkisi karıştırılmamalıdır.
Üçüncü madde bir tasarım ilkesidir: gelen veriyi sessizce değiştirip kabul etmek, istemcinin gönderdiğiyle kaydedilenin farklı olmasına yol açar — istemci ne olduğunu bilmez ve hata ayıklama imkânsızlaşır.
Baştaki ve sondaki boşlukları temizlemek gibi zararsız işlemler kabul edilebilir.
Ancak bir metni kısaltmak veya karakterleri değiştirmek reddetmeyi gerektirir.
Kural şudur: veri beklenen biçimde değilse düzeltmeye çalışma, hata döndür.
Şema Değişikliği
- Yeni zorunlu alan kırıcıdır.
- Yeni isteğe bağlı alan güvenlidir.
- Alan kaldırmak kırıcıdır.
- Kısıt sıkılaştırmak kırıcıdır.
Dördüncü madde sık gözden kaçar: bir metin alanının üst sınırını düşürmek, o sınırın üstünde veri gönderen mevcut istemcileri anında kırar — kısıt eklemek de kaldırmak kadar kırıcı bir değişikliktir.
Bu tür değişiklikler sürüm yönetimiyle veya geçiş süresiyle yapılmalıdır.
İkinci madde ise güvenli genişletmedir ve tercih edilmelidir.
Birinci madde ise varsayılan değer tanımlanarak yumuşatılabilir.
Şemayı Belgelemek
| Yaklaşım | Değeri |
|---|---|
| Ayrı belge yazmak | Eskir |
| Şemadan üretmek | Her zaman güncel |
| Örnek istek sunmak | Çok yardımcı |
İkinci satır bakım sorununu kökten çözer: doğrulama şemasından otomatik üretilen belge, kodla her zaman uyumlu kalır — elle yazılan belgeler ise ilk değişiklikte eskir ve yanlış bilgi vermeye başlar.
Yanlış belge, hiç belge olmamasından daha zararlıdır.
Üçüncü satır ise geliştiricilerin en çok istediği şeydir. Çalışan bir örnek, uzun açıklamalardan hızlı anlaşılır.
Bu örnek gerçekten çalışmalı ve test edilmelidir.
API servislerinizi barındırırken kaynak sınırlarını kontrol edebilmeniz gerekir; sanal sunucu barındırma çözümleri üzerinde istek boyutu ve işçi süreç ayarlarını kendiniz yapılandırabilirsiniz.
Sonuç
İstemci tarafı doğrulama asla güvenlik katmanı değildir: API'nize doğrudan istek gönderen biri o kontrolü tamamen atlar. Şema tabanlı doğrulamada fazladan alanları reddedin — bu, istemcinin gönderdiği bir "yetki" alanının kazara işlenmesini engeller. Dizilere mutlaka sınır koyun; sınırsız bir dizi alanı, tek istekle sunucunuzu meşgul etmenin en kolay yoludur. Ve tüm doğrulama hatalarını tek yanıtta döndürün.
Sıkça Sorulan Sorular (SSS)
İstemcide doğruluyorum, yeterli değil mi?
Değil. İstemci tarafı doğrulama yalnızca kullanıcıya hızlı geri bildirim içindir; API'nize doğrudan istek gönderen biri onu tamamen atlar ve bu tarayıcı araçlarıyla saniyeler içinde yapılabilir. Sunucu tarafında her istek yeniden doğrulanmalıdır.
Fazladan alanları neden reddetmeliyim?
Sessizce yok saymak yerine reddetmek, istemcinin gönderdiği beklenmeyen bir alanın kazara işlenmesini engeller — kütle atama açığının temel savunması budur. Ayrıca istemci tarafındaki yazım hatalarını da yakalar; yanlış yazılan alan adı sessizce göz ardı edilmez.
Boş değer ile alanın hiç gelmemesi aynı mı?
Değil ve karıştırmak veri kaybettirir. Alanın hiç gönderilmemesi "değiştirme", boş gönderilmesi "temizle" anlamına gelir. Bu ayrım özellikle kısmi güncelleme yapan uç noktalarda kritiktir.
Hataları nasıl döndürmeliyim?
Tümünü tek yanıtta, alan bazında ve makine okunabilir kodlarla. İlk hatada durmak istemcinin formu defalarca göndermesine yol açar. Veritabanı hata mesajlarını asla dışarıya vermeyin — iç yapınızı sızdırır.
