REST API Tasarımı ve Next.js Route Handlers

Bu rehberde ne öğreneceksiniz?

Bu yazı bir haber özeti değil; adım adım uygulayabileceğiniz bir öğretici makale (tutorial) formatındadır. Her bölümün sonunda pratik çıkarımlar ve üretim ortamında karşılaşacağınız senaryolar yer alır.

• Tutarlı REST kaynak modeli tasarlamak
• Pagination ve filtreleme contract'ı tanımlamak
• Validation ve hata gövdesi standardı oluşturmak
• Rate limit ve auth middleware uygulamak

Ön koşullar

Rehberi verimli takip etmek için aşağıdaki bilgilere aşina olmanız önerilir. Eksik hissettiğiniz konularda ilgili bölümde ek kaynak ipuçları bulacaksınız.

• HTTP metodları ve status kodları
• JSON ve TypeScript
• Temel güvenlik (auth header, CORS)

Güncellik ve teknoloji yığını

Makale 2026 itibarıyla güncellenmiştir. Örnekler ve API referansları şu yığınla uyumludur: Next.js 16 Route Handlers, Zod validation, Prisma 7. Eski sürüm dokümantasyonu ile karıştırmamak için major versiyon farklarını özellikle belirttik.

Framework sürümleri hızla değişir; kalıcı olan prensipler (güvenlik, katman ayrımı, ölçüm) bu rehberin omurgasını oluşturur.

Bölüm 1: URL ve kaynak isimlendirme

İsimler çoğul: /api/blog, /api/blog/[id]. Fiil kullanmayın; HTTP metodu fiili taşır.

• GET — okuma
• POST — oluşturma
• PATCH — kısmi güncelleme
• DELETE — soft delete tercih

Bölüm 2: Handler iskeleti

Her handler: auth → validate → service → map → response. Try/catch ile structured log; kullanıcıya generic 500, log'a detay.

Adım adım uygulama

Aşağıdaki sırayı takip edin. Her adımı tamamlamadan bir sonrakine geçmeyin; özellikle güvenlik ve veri katmanı adımları atlanmamalıdır.

1. Query parametrelerini Zod ile parse edin.
2. Başarılı yanıtta tutarlı { data } veya { data, meta } kullanın.
3. 201 Created sonrası Location header düşünün.

export async function GET(request: Request) {
  const session = await auth();
  const { searchParams } = new URL(request.url);
  const tag = searchParams.get('tag') ?? undefined;
  const blogs = await getPublishedBlogs({ tag, limit: 20 });
  return NextResponse.json({ data: blogs.map(mapBlogToResponse) });
}

Bölüm 3: Pagination ve filtreleme

Offset pagination basit; büyük tablolarda cursor (?cursor=uuid) tercih edin. Meta alanında hasMore ve nextCursor döndürün.

Bölüm 4: Güvenlik

Rate limit, CORS whitelist, input sanitization. Admin endpoint'lerde role kontrolü zorunlu.

Dikkat: Hata mesajında stack trace veya SQL detayı asla dönmeyin.

Bölüm 5: Versiyonlama ve deprecation

URL path versiyonu (/api/v2/blogs) veya Accept header ile contract evrimi yönetin. Breaking change öncesi Sunset header kullanın.

Eski istemciler için minimum 6 ay destek penceresi tanımlayın. OpenAPI changelog ile PR review bağlayın.

Adım adım uygulama

Aşağıdaki sırayı takip edin. Her adımı tamamlamadan bir sonrakine geçmeyin; özellikle güvenlik ve veri katmanı adımları atlanmamalıdır.

1. v2 route namespace açın
2. v1 için deprecation response header
3. Metrik: v1 trafik oranı sıfıra yaklaşınca kapat

Sık yapılan hatalar

Aşağıdaki tuzaklar eğitim ortamlarında nadiren, production'da ise pahalıya mal olur. Code review checklist'inize eklemenizi öneririz.

• 200 OK ile hata gövdesi döndürmek
• Tutarsız JSON şekilleri (bazen array bazen object)
• Validation'sız searchParams kullanımı

Pratik alıştırmalar

Okumak yeterli değildir; öğrenmeyi pekiştirmek için küçük bir side-project veya mevcut kod tabanınızda şu görevleri uygulayın:

1. Blog listesine tag ve category query filtresi ekleyin
2. 422 validation response şemasını dokümante edin

Özet ve sonraki adımlar

Bu rehberdeki prensipleri tek seferde tüm projeye uygulamaya çalışmayın. Önce tek bir route veya modül seçin, ölçün, sonra yaygınlaştırın.

• OpenAPI (Swagger) spec üretin
• GraphQL öğreticisi ile alternatif API stilini karşılaştırın