
Bir API’nin kötü tasarlandığını genellikle ilk gün anlamazsınız. Üçüncü istemci entegre olduğunda, mobil ekip eski sürümü bırakamadığında ya da bir hata mesajı yüzünden destek ekibi saatlerce log taradığında anlarsınız. O noktada yapılan her düzeltme, artık birilerinin bağımlı olduğu bir sözleşmeyi bozmak demektir. Bu yazıdaki yedi kural, sahada en sık geri dönüp düzeltmek zorunda kaldığımız kararlardan derlendi.
Önce Ortak Bir Zemin: REST API Nedir?
"rest api nedir" sorusunun kısa cevabı şu: REST, Roy Fielding’in doktora tezinde tanımladığı bir mimari stil; bir protokol ya da standart değil. Kaynakları URI’lerle adreslersiniz, bu kaynaklar üzerinde HTTP’nin kendi yöntemleriyle işlem yaparsınız, sunucu istemcinin oturum durumunu tutmaz ve yanıtlar önbelleğe alınabilir olarak işaretlenebilir.
Pratikte "REST API" dediğimiz şeylerin çoğu, Fielding’in tarif ettiği her kısıtı (özellikle hipermedya kısmını) uygulamaz. Bu bir kusur sayılmak zorunda değil. Önemli olan, HTTP’nin zaten sunduğu anlamları yeniden icat etmemek ve tüketicinin tahmin edebileceği bir yapı kurmak. Aşağıdaki kurallar da bu tahmin edilebilirlik üzerine kurulu.
Kaynakları ve Yöntemleri Doğru Kurmak
Kural 1: URI’ler isimdir, eylemi HTTP yöntemi söyler
/getCustomer?id=42 ya da /createOrder gibi uç noktalar, RPC alışkanlığının REST kılığına girmiş hâlidir. Kaynak bir isimdir ve çoğul kullanılır: /customers/42, /orders. Ne yapılacağını yöntem belirler: GET okur, POST yeni kayıt oluşturur, PUT tamamen değiştirir, PATCH kısmen günceller, DELETE siler.
İç içe kaynaklarda bir seviyede durmak çoğu zaman yeterlidir. /customers/42/orders anlaşılır; /customers/42/orders/7/items/3/discounts ise istemciyi gereksiz bir hiyerarşiye bağlar. Bir sipariş kalemine kendi kimliğiyle doğrudan erişilebiliyorsa, ona üst düzey bir yol vermek daha esnektir.
Kural 2: Yöntemlerin güvenlik ve idempotent sözlerini bozmayın
GET bir şey değiştirmemeli. Bunu çiğneyen ekipler, bir önbelleğin ya da bağlantıları önceden yükleyen bir aracın kayıtları sessizce güncellediğini fark ettiğinde iş işten geçmiş olur. PUT ve DELETE idempotenttir: aynı isteği iki kez göndermek, bir kez göndermekle aynı sonucu doğurmalıdır.
POST ise idempotent değildir ve ağ kopmalarında asıl sorun burada çıkar. Ödeme ya da sipariş oluşturma gibi işlemlerde istemcinin bir idempotency anahtarı göndermesine izin verin; sunucu aynı anahtarla gelen ikinci isteği yeni kayıt açmadan ilk yanıtla karşılasın. Mobil istemcilerin zayıf bağlantıda yeniden deneme yaptığı her sistemde bu küçük ek, mükerrer kayıt şikâyetlerini kökünden keser.
Kural 3: Koleksiyonları baştan sayfalayın ve filtrelenebilir yapın
"Şimdilik yüz kayıt var" diye sayfalamasız bırakılan bir liste uç noktası, bir yıl sonra yüz bin kayıt döndürmeye başlar. Sayfalamayı sonradan eklemek, yanıt biçimini değiştirmek demektir; yani kırıcı bir değişiklik. Hızla büyüyen ya da sık değişen veri setlerinde imleç (cursor) tabanlı sayfalama, offset yaklaşımındaki kayma ve performans sorunlarını önler. Filtre ve sıralama parametrelerini de tutarlı adlandırın: bir uç noktada sort=-createdAt, diğerinde orderBy=created_at&dir=desc görmek, tüketiciye her uç noktanın ayrı bir ekip tarafından yazıldığını söyler.
Hata, Durum ve Değişimle Barışık Olmak
Kural 4: Durum kodları gerçeği söylesin
Her şeye 200 dönüp gövdeye "success": false yazmak, istemcideki her katmanın (proxy, izleme aracı, yeniden deneme mantığı) HTTP’nin size bedavaya verdiği bilgiyi kaybetmesi demektir. Oluşturma işlemlerinde 201 ve yeni kaynağın adresini Location başlığında verin. Kimlik doğrulanmamışsa 401, doğrulanmış ama yetkisi yoksa 403 kullanın. Doğrulama hatalarında 400 veya 422, sürüm çakışmalarında 409, hız sınırında 429 ve mümkünse Retry-After.
Kural 5: Hata gövdesini bir sözleşme olarak tasarlayın
Durum kodu "ne tür" bir sorun olduğunu söyler; gövde ise "tam olarak ne" olduğunu. Bunun için sıfırdan format icat etmek yerine RFC 9457 (Problem Details for HTTP APIs) yapısını temel almak mantıklıdır. İyi bir hata yanıtında şunlar bulunur:
- Makinenin karşılaştırabileceği sabit bir hata tipi ya da kodu
- İnsanın okuyabileceği kısa bir açıklama
- Doğrulama hatalarında hangi alanın neden reddedildiği
- Destek ekibinin loglarda arayabileceği bir istek kimliği
Yığın izi, SQL hatası ya da iç servis adları ise asla gövdeye düşmemeli. Bunlar hem güvenlik açığı hem de tüketiciyi sizin iç yapınıza bağlayan istemsiz bir sözleşmedir.
Kural 6: Versiyonlamayı ilk sürümden planlayın
Versiyonlama, kırıcı değişikliğe ihtiyaç duyduğunuz gün düşünülecek bir konu değil. Asıl disiplin, kırıcı değişikliği nadir kılmaktır: yeni alan eklemek kırıcı değildir, alan silmek, adını ya da tipini değiştirmek kırıcıdır. İstemcileri bilinmeyen alanları yok sayacak şekilde yönlendirin; böylece API’yi geriye uyumlu biçimde büyütebilirsiniz. Kaçınılmaz bir kırılma geldiğinde ise eski sürümü bir kullanımdan kaldırma takvimiyle yaşatın ve bunu yanıt başlıklarında da duyurun.
Sözleşmeyi Yazıya Dökmek
Kural 7: Dokümantasyon koddan önce gelir
"api dokümantasyonu nasıl yazılır" sorusuna en verimli cevap, onu ayrı bir iş olarak görmemektir. OpenAPI ile tasarımı önce sözleşme olarak yazdığınızda, ön yüz ekibi sahte sunucuyla hemen çalışmaya başlar, sözleşme testleri CI’da otomatik koşar ve referans dokümanı kendiliğinden güncel kalır.
Ama üretilmiş referans tek başına yetmez. Gerçekten işe yarayan dokümanlarda kimlik doğrulamanın ilk on dakikası adım adım anlatılır, her uç nokta için gerçekçi istek ve yanıt örneği bulunur, hata kodlarının anlamı tek bir sayfada toplanır ve bir değişiklik günlüğü tutulur. Ekip içinde paylaşmak için iyi bir egzersiz de, bilinen restful api örnekleri arasından birkaç büyük ödeme ya da iletişim platformunun dokümanlarını açıp sizin sayfanızla yan yana okumaktır. Fark genellikle örneklerin gerçekçiliğinde ortaya çıkar.
Bu noktada sık gelen bir soru da "rest vs graphql" tartışması. GraphQL, istemcinin tam olarak hangi alanları istediğini belirlemesine izin verir ve çok farklı ekranları besleyen ön yüzlerde ciddi kolaylık sağlar. Karşılığında önbellekleme, hız sınırlama ve sorgu maliyeti kontrolü daha fazla emek ister. Kaynakları net, tüketicileri çeşitli ve dış entegrasyonu ağırlıklı bir sistemde REST hâlâ daha az sürprizli bir tercihtir. İkisini aynı ürün içinde, farklı tüketiciler için yan yana kullanan ekipler de az değil.
Sıkça Sorulan Sorular
REST ile SOAP arasındaki fark nedir?
SOAP, XML tabanlı ve kendi zarf yapısı, WSDL ile tanımlı katı sözleşmesi ve WS-Security gibi eklenti standartları olan bir protokoldür. REST ise bir mimari stildir; HTTP’nin yöntemlerini ve durum kodlarını doğrudan kullanır ve genellikle JSON ile çalışır. SOAP bugün daha çok bankacılık ve kamu entegrasyonları gibi köklü sistemlerde yaşarken, yeni web ve mobil API’lerin büyük çoğunluğu REST ile tasarlanıyor.
API versiyonlama nasıl yapılır?
En yaygın ve en görünür yöntem, sürümü URI’ye koymaktır: /v1/orders. Alternatif olarak sürüm özel bir başlıkta ya da Accept başlığındaki medya tipiyle belirtilebilir; bu yöntem URI’leri temiz tutar ama hata ayıklamayı biraz zorlaştırır. Hangisini seçerseniz seçin, tüm API boyunca tek bir yöntem kullanın ve yalnızca kırıcı değişikliklerde ana sürümü artırın.
HTTP durum kodları nasıl doğru kullanılır?
Önce sınıfı doğru seçin: 2xx başarı, 4xx istemcinin düzeltebileceği hata, 5xx sunucu tarafı sorun. İstemcinin hatasını 500 ile, sunucunun hatasını 400 ile döndürmek, yeniden deneme ve alarm mantığını yanlış yöne sürükler. Ardından sınıf içinde en anlamlı kodu kullanın ve gövdede ayrıntıyı tutarlı bir hata formatıyla verin.
Bir Sonraki API’nizde İlk Hafta Neye Bakmalı?
Yedi kuralın hepsini aynı anda uygulamaya çalışmak yerine, en pahalı geri dönüşleri önleyenlerle başlayın: kaynak adlandırması, hata formatı ve versiyon stratejisi. Bunları tek sayfalık bir API stil rehberine yazıp ekibin ilk pull request incelemelerinde referans almasını sağlarsanız, geri kalanı zamanla oturur. Asıl hedef, API’yi kullanan birinin dokümana bakmadan bir sonraki uç noktanın nasıl davranacağını tahmin edebilmesi.
Bulut üzerinde API geliştirme, DevOps süreçleri ve Google Cloud mimarisi tarafında destek arayan ekipler için Global IT, 2006’dan bu yana edindiği deneyimle bu yolculukta yanınızda olabilir.



