Frontend ve backend arasında API sözleşmesini (contract) nasıl yönetirsiniz? OpenAPI, tRPC ve GraphQL codegen yaklaşımlarını karşılaştırın.

Amaç, backend bir alanı değiştirdiğinde frontend'in bunu çalışma zamanında değil derleme zamanında fark etmesidir. Bunun için API'nin tek bir kaynaktan tanımlanıp tiplerin otomatik üretilmesi gerekir.

OpenAPI örneği

# Backend'in ürettiği şemadan tipleri üret
npx openapi-typescript https://api.ornek.com/openapi.json -o src/api/schema.ts

import createClient from "openapi-fetch";
import type { paths } from "./api/schema";

const api = createClient<paths>({ baseUrl: "/api" });
const { data, error } = await api.GET("/users/{id}", { params: { path: { id: "42" } } });
// data tipi şemadan gelir; alan adı değişirse derleme hata verir

tRPC örneği

// server
export const appRouter = router({
  userById: publicProcedure.input(z.object({ id: z.string() }))
    .query(({ input }) => db.user.findUnique({ where: { id: input.id } })),
});
// client: trpc.userById.useQuery({ id: "42" }) tamamen tipli

Pratik kurallar

• Code-first (koddan şema üretmek: NestJS, FastAPI, Zod-to-OpenAPI) veya schema-first (önce şema, sonra kod) seçin ama tek kaynak olsun.
• CI'da şema farkını kontrol edin; kırıcı değişiklik (alan silme, tip değiştirme) PR'da yakalansın (oasdiff, GraphQL Inspector).
• Tipler derleme zamanı garantisidir; çalışma zamanında gelen veriyi de (özellikle dış API'lerden) Zod ile doğrulamak iyi pratiktir.
• tRPC, client ve server aynı repoda ve TypeScript olduğunda harikadır; mobil uygulama veya üçüncü taraf tüketici varsa OpenAPI daha uygundur.