Frontend Bakış Açısıyla API Tasarımı

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 Sadece Backend İçin Yazılmaz

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’in Beklediği Şey: Predictability

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.

İyi API Frontend Complexity’sini Azaltır

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.

Overfetching vs Underfetching

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.

Frontend’in En Sevdiği Backend Developer

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.

API Design = Developer Experience

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.

Sonuç

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.