REST API Tasarımı: İyi Bir API İçin Temel İlkeler

İyi tasarlanmış bir API, dokümana bakmadan tahmin edilebilir. Kötü tasarlanmış olan ise her çağrıda sürpriz yaşatır. Aradaki fark, baştan konulan birkaç basit ilkeyle ortaya çıkar.Bu yazı, sağlam bir rest api kurmak isteyen geliştiriciler için. Kaynak isimlendirmeden hata yönetimine kadar günlük çalışmanda işine yarayacak ilkeleri pratik örneklerle ele alıyoruz. Bir rest api, istemci ile sunucu arasındaki sözleşmedir. Bu sözleşme ne kadar tutarlıysa, entegrasyon o kadar kolay olur.

Kaynak isimlendirmede tutarlılık

URL'ler kaynakları temsil eder, eylemleri değil. Bu yüzden adres satırında fiil değil, isim kullanırsın. Yani /getUsers değil, /users doğru olanıdır. Eylemi belirleyen şey HTTP metodudur.Koleksiyonlar için çoğul isim tercih et. Bir kullanıcı kaydına /users/42 ile ulaşırsın. İç içe kaynaklarda hiyerarşiyi sığ tut. İki seviyeden derine inmek adresleri okunaksız hale getirir. Bir kullanıcının siparişleri için /users/42/orders yeterince açıktır.Adreslerde küçük harf ve tire kullan. Alt çizgi ve büyük harf karışıklığı sürekli hata kaynağı olur. Tutarlı bir biçim, ekibinin tahmin gücünü artırır.

HTTP metodlarını doğru kullan

Her metodun net bir anlamı vardır. Bu anlamlara saygı gösterirsen istemci tarafı çok daha az sürpriz yaşar. Aşağıdaki tablo en sık kullanılan metodları özetliyor.

GET çağrıları yan etki üretmemeli. Aynı isteği iki kez yapmak veriyi değiştirmemeli. PUT ve DELETE de idempotent olmalı, yani tekrarlanması sonucu bozmamalı. Bu kurallar önbellekleme ve yeniden deneme mantığını sağlam tutar.

Anlamlı durum kodları döndür

Durum kodu, istemcinin cevabı anlamasının en hızlı yoludur. İstemci, gövdeyi ayrıştırmadan ne olduğunu kodun kendisinden anlamalı. Her şeye 200 dönmek en sık yapılan hatadır.

• 200 OK başarılı bir okuma veya güncelleme.
• 201 Created yeni bir kaynak oluşturuldu.
• 400 Bad Request istek geçersiz veya eksik.
• 401 Unauthorized kimlik doğrulama gerekiyor.
• 404 Not Found kaynak bulunamadı.
• 500 Internal Server Error sunucu tarafında bir sorun var.

Doğru kod seçimi, istemcinin doğru tepkiyi vermesini sağlar. Daha derin bir referans için MDN HTTP durum kodları belgesine bakabilirsin.

Versiyonlama ve sayfalama

API'n büyüdükçe değişiklik yapman kaçınılmaz olur. Versiyonlamayı en baştan planla. Bir kırıcı değişiklik, eski istemcileri tek seferde çökertmemeli. En yaygın yaklaşım adres içinde versiyon taşımaktır: /v1/users.Büyük koleksiyonları asla tek seferde döndürme. Sayfalama, hem sunucuyu hem istemciyi rahatlatır. limit ve offset parametreleriyle ya da imleç tabanlı bir yaklaşımla sayfaları böl. Yanıtın içine toplam sayı ve sonraki sayfa bağlantısını koymak istemcinin işini kolaylaştırır.Filtreleme ve sıralama için sorgu parametreleri kullan. /users?status=active&sort=created_at gibi bir adres okunabilir kalır ve adres yapısını bozmaz.

Hata yönetimi ve kimlik doğrulama

Hata yanıtları da tasarımın bir parçasıdır. Tutarlı bir hata gövdesi, istemcinin sorunu programatik olarak ele almasını sağlar. Her hatada aynı yapıyı döndür.

{
  "error": {
    "code": "validation_error",
    "message": "E-posta alanı zorunludur",
    "field": "email"
  }
}

Kimlik doğrulamada her isteği bağımsız düşün. REST mimarisi durumsuzdur, yani sunucu istemciyi oturumda hatırlamaz. Bunun yerine her istek kendi kimlik bilgisini taşır. Genelde bunu bir Authorization başlığındaki token ile yaparsın.API anahtarları, OAuth 2.0 ve JWT en yaygın seçeneklerdir. Hangisini seçersen seç, trafiği her zaman HTTPS üzerinden taşı. Token'ları log'lara veya adres satırına asla yazma. Bu küçük disiplin, ileride büyük güvenlik açıklarını önler.

Bir rest api'yi pratiğe dökmek

Bir kaynak için tasarımı bir arada görmek faydalı olur. Aşağıdaki uç noktalar tek bir users kaynağının nasıl şekillendiğini gösteriyor.

Başarılı bir oluşturma çağrısının yanıtı şöyle görünebilir:

{
  "id": 42,
  "name": "Ayse Yilmaz",
  "email": "ayse@example.com",
  "created_at": "2026-06-14T10:00:00Z"
}

Bu ilkeleri bir araya getirdiğinde ortaya tahmin edilebilir ve bakımı kolay bir API çıkar. Tutarlı isimlendirme, doğru metodlar ve anlamlı kodlar entegrasyon süresini kısaltır. Hata yönetimi ve güvenlik ise üretimde başını ağrıtmaz.Kritm Cloud Solutions olarak web, mobil ve API tarafında özel yazılım geliştiriyoruz. Sağlam bir backend kurmak ya da onu güvenilir bir altyapıda yayına almak istersen yanındayız. Hizmetlerimizi inceleyebilir, projen için bizimle iletişime geçebilirsin.