API tasarımı çoğu zaman backend sorumluluğu gibi görülür. Ama gerçekte kötü tasarlanmış bir API’nin yükünü en fazla frontend tarafı hisseder. Tutarsız response yapıları, gereksiz nested veri, anlamsız endpoint’ler ve öngörülemeyen davranışlar frontend geliştirme hızını ciddi şekilde düşürür. Bu yazıda API tasarımına frontend engineer perspektifinden bakıyor ve iyi bir API’nin neden sadece “çalışan” değil, tüketilebilir olması gerektiğini konuşuyoruz.
Frontend geliştirirken bazı API’lerle çalışırsın ve her şey akıp gider. Endpoint’ler nettir, response yapıları tutarlıdır, veri öngörülebilir gelir. Component’i yazarsın, state’i bağlarsın ve iş ilerler.
Bir de tam tersi vardır.
Her endpoint farklı davranır.
Bir yerde data, bir yerde result, başka yerde direkt array döner.
Bazı alanlar null, bazıları hiç yoktur.
Pagination yapısı endpoint’e göre değişir.
Error formatı bile standart değildir.
Ve bir noktadan sonra frontend tarafında şunu fark edersin:
Sen artık feature geliştirmiyorsundur. API’yi “idare etmeye” çalışıyorsundur.
Aslında kötü API tasarımının en büyük maliyetini çoğu zaman frontend öder.
API tasarımında en sık gördüğüm problemlerden biri şu:
API’lerin sadece backend mantığıyla düşünülmesi.
Örneğin backend tarafında database yapısı nasıl organize edildiyse response da birebir öyle dönülüyor. Relation’lar iç içe nested şekilde geliyor. Frontend tarafında aslında ihtiyaç olmayan tonla veri taşınıyor.
Sonra frontend tarafında şu başlıyor:
Mapping işlemleri
Defensive coding
Null check kaosu
Transformation layer’ları
“Bu endpoint burada neden böyle dönüyor?” soruları
Bir süre sonra business logic’in yarısı frontend’e taşınmış oluyor.
Halbuki iyi API tasarımı sadece veriyi döndürmek değildir.
Tüketilebilir veri döndürmektir.
Frontend tarafında en değerli şeylerden biri öngörülebilirlik.
Çünkü UI state’i zaten karmaşık bir alan. Eğer API davranışı da tutarsızsa complexity katlanıyor.
Örneğin şöyle bir yapı düşün:
Tüm endpoint’lerde aynı response pattern’inin kullanılması frontend tarafında inanılmaz rahatlık sağlar.
Çünkü artık şunu düşünmezsin:
“Bu endpoint burada nasıl dönüyordu?”
Aynı durum error handling için de geçerli.
Bazı sistemlerde:
Bir endpoint 500
Diğeri 200 + error
Başkası düz string
Bir diğeri farklı field isimleri
dönüyor.
Bu noktada frontend tarafında gerçek problem hata yönetimi değil, belirsizlik oluyor.
Bence iyi API’nin en önemli özelliklerinden biri frontend complexity’sini düşürmesi.
Çünkü kötü API tasarımı frontend’i sürekli ekstra karar vermeye zorlar.
Örneğin:
gibi erişimler çoğu zaman API tasarımının yan etkisi.
Frontend burada UI geliştirmek yerine veriyle savaşmaya başlıyor.
İyi API ise frontend’in ihtiyacı olan shape’i düşünür.
Çünkü frontend çoğu zaman relational database düşünmez.
Ekran düşünür.
Bu konu özellikle büyük projelerde çok hissediliyor.
Bazı endpoint’ler gereksiz fazla veri döner.
Bazıları ise eksik döner ve frontend 3 farklı request atmak zorunda kalır.
İkisi de problem.
Mesela bir ürün kartı için:
product
stock
pricing
campaign
verilerini ayrı ayrı çekiyorsan frontend tarafında orchestration complexity oluşuyor.
Ama diğer uçta da tüm sistemi tek response’a gömmek var. O da gereksiz payload ve performans maliyeti yaratıyor.
İyi API burada denge kuruyor.
Bence frontend developer’ların en rahat çalıştığı backend engineer tipi şu:
“Frontend’in problemiyle ilgilenen backend engineer.”
Çünkü iyi backend engineer sadece endpoint yazmıyor.
Consumer’ı düşünüyor.
“Bu response frontend’de nasıl kullanılacak?”
“Bu alan gerçekten gerekli mi?”
“Bu naming anlaşılır mı?”
“Bu yapı büyür mü?”
Bu bakış açısı olduğunda ekipler inanılmaz hızlanıyor.
Birçok kişi DX (Developer Experience) denince sadece frontend tooling düşünüyor. Ama API tasarımı da doğrudan DX konusu.
Çünkü kötü API:
Daha fazla bug
Daha fazla mapping
Daha fazla edge-case
Daha fazla mental load
üretiyor.
İyi API ise frontend tarafında düşünme yükünü azaltıyor.
Ve bence iyi mühendislik tam olarak burada başlıyor zaten:
Sadece çalışan sistem kurmak değil, diğer engineer’ların hayatını kolaylaştırmak.
API tasarımı backend’in “çıktısı” değildir.
Frontend ile backend arasında kurulan iletişim dilidir.
Bu dil ne kadar tutarlı, öngörülebilir ve sade olursa ekipler o kadar hızlı ilerler.
Çünkü frontend geliştirme sürecindeki en büyük kayıplardan biri rendering problemi değil, veriyle mücadele etmektir.
İyi API tasarımı sadece backend kalitesini değil, frontend hızını ve ekip verimliliğini de doğrudan etkiler.
