Bir API'nin sözleşmesi genelde iki yerde tanımlanır: backend'de ve frontend'de. İkisini elle senkron tutmaya çalıştığınız her proje, er ya da geç bir noktada sahadan farklı bir response şekliyle karşılaşır.
Node.js/.NET backend'leri ve Next.js frontend'lerini aynı monorepo'da tutmadığım projelerde bile, en azından response tiplerini ayrı bir 'types' paketi olarak çıkarıp her iki tarafın da aynı kaynaktan import etmesini sağladım. Bu basit disiplin, 'backend bir alanı yeniden adlandırdı ama frontend hâlâ eski adı bekliyor' türünden hataları neredeyse sıfırladı.
Zod gibi şema doğrulama kütüphaneleri burada ikinci kritik katman. Şemayı bir kere tanımlayıp ondan TypeScript tipini türetmek (z.infer), hem çalışma zamanı doğrulamasını hem derleme zamanı tip güvenliğini aynı yerden besliyor. API'ye gelen body'yi doğrudan tipe cast etmek yerine şemadan geçirmek, üretimde sessizce yanlış veri kabul etmenin önüne geçiyor.
Hata response'larını da aynı disiplinle tipliyorum: başarılı ve başarısız durumlar için ayrı, discriminated union tipler kullanmak, frontend'de 'data muhtemelen var ama olmayabilir' türünden belirsiz kontrolleri ortadan kaldırıyor.
Tip güvenliği bir kerede kurulup unutulan bir şey değil; her endpoint eklendiğinde tekrar edilen bir alışkanlık.
{ }