API Tasarımında Nested Resource'lar: Flatlama Neden Daha İyi Olabilir

REST API'lerde nested resource'lar ilk bakışta mantıklı görünür. Örneğin /users/123/posts/456/comments/789 gibi bir yapı veri ilişkisini doğal yansıtır. Ancak gerçek uygulamada bu tasarım sıkça sorun yaratır.

Nested yapının temel sorunu karmaşıklıktır. İstemci tarafında her endpoint'i inşa etmek zahmetlidir; URL'yi yanlış yazmak kolay, hata ayıklama zordur. Bir comment'i güncellemek için /users/123/posts/456/comments/789 yazarken, user ID'yi yanlış girersen hiç fark etmeyebilirsin, sadece 404 alırsın. Flat yapıda /comments/789 yeterlidir; bir kaynak bir endpoint, bitti.

Performans açısından da olumsuz etkiler vardır. Nested endpoint'ler sıklıkla cascade sorgularına yol açar. Comment'i almak için önce user'ı doğrulamak, sonra post'u kontrol etmek gerekebilir. Her adımda veritabanına gidişler artar. Flat yapıda doğrudan comment'e erişirsin; kimlik doğrulama ve yetkilendirme daha basit ve hızlı olur.

Bakım ve genişletilebilirlik de sorunludur. Üç seviye derinliğindeki nested endpoint'ler kod tabanında karışıklık yaratır. Bir post aynı anda birden fazla user'a ait olabilirse ne olur? Nested yapı bu senaryoyu desteklemez; refactoring gerekir. Flat yapı böyle değişikliklere hazırdır.

Gerçek dünyada başarılı API'ler (GitHub, Stripe, Twilio) flat veya maksimum bir seviye deep nested yapı kullanır. /repos/{owner}/{repo}/issues yerine /issues?repo_id=X tercih ederler. Filtreleme parametreleri daha esnek ve bakımı kolaydır.

Nested resource'lar tek bir durumda yararlıdır: ilişki doğru-bir ve hiç değişmeyecekse. Örneğin /users/123/profile makul olabilir. Ama /users/123/posts/456/comments gibi derin yapılar pratikte sadece teknik borç biriktirir.

Flat API'ler daha az şık görünebilir, fakat daha hızlı, güvenli ve bakımı kolay. Tasarımda gösteriş yerine işlevselliği seç.