REST API: Kaynak Odaklı Arayüzlerin Çalışma Mantığı

REST API nedir?

REST API, yazılımların birbiriyle HTTP üzerinden konuşmasını sağlayan ve verileri "kaynak" olarak ele alan bir arayüz tarzıdır. REST (Representational State Transfer), Roy Fielding'in doktora tezinde tanımladığı bir mimari stilin adıdır; belirli bir protokol ya da ürün değil, bir dizi tasarım kısıtıdır. Bu kısıtlara uyan arayüzlere "RESTful API" denir.

Günlük kullanımda REST API denince çoğunlukla şu akla gelir: adresi olan kaynaklar (örneğin müşteriler, siparişler), bu kaynaklar üzerinde HTTP metotlarıyla yapılan işlemler ve genellikle JSON biçiminde dönen yanıtlar. Mobil uygulamaların, web sitelerinin ve sistem entegrasyonlarının büyük bölümü bu şekilde veri alışverişi yapar.

REST'in temel kısıtları

Fielding'in tanımında REST, şu mimari kısıtların bir araya gelmesiyle oluşur:

• İstemci-sunucu ayrımı: arayüz tarafı ile veri saklama tarafı birbirinden bağımsız gelişir
• Durumsuzluk: her istek, işlenmesi için gereken tüm bilgiyi taşır; sunucu istekler arası oturum durumu tutmaz
• Önbellekleme: yanıtlar önbelleğe alınabilir ya da alınamaz olarak işaretlenir
• Tekdüze arayüz: kaynakların tanımlanması, temsiller üzerinden değiştirilmesi, kendini açıklayan mesajlar ve hipermedya ile uygulama durumunun yönetimi
• Katmanlı sistem: istemci, arada ağ geçidi ya da önbellek gibi katmanlar olduğunu bilmek zorunda değildir
• İsteğe bağlı kod indirme: sunucu istemciye çalıştırılabilir kod gönderebilir

Uygulamada çoğu "REST" API bu kısıtların tamamını, özellikle hipermedya bölümünü, uygulamaz; bu yüzden "REST benzeri" ya da "HTTP tabanlı" arayüz demek bazen daha doğrudur.

Bir REST isteği nasıl işler?

İstemci, bir kaynağın adresine (URI) HTTP metoduyla istek gönderir. Sunucu işlemi yapar ve durum koduyla birlikte yanıt döner.

Örneğin bir mağazanın siparişlerini yöneten arayüz düşünelim. Siparişlerin listesi, siparişler koleksiyonunu temsil eden adrese yapılan GET isteğiyle alınır. Yeni sipariş, aynı adrese POST ile gönderilen bir gövdeyle oluşturulur. Tek bir siparişin güncellenmesi o siparişin kendi adresine PUT ya da PATCH ile, silinmesi DELETE ile yapılır.

Sunucunun yanıtındaki durum kodu sonucu bildirir: başarı, oluşturulma, yetki yok, kaynak bulunamadı ya da sunucu hatası gibi. İstemci bu koda göre davranır. Gövde genellikle JSON'dur ama başka biçimler de kullanılabilir.

HTTP metotları ve anlamları

Metotların anlamı tutarlı kullanılırsa arayüz öngörülebilir olur:

• GET: kaynağı okur; sunucuda değişiklik yapmamalıdır
• POST: yeni kaynak oluşturur ya da bir işlem tetikler
• PUT: kaynağı bütünüyle değiştirir; aynı istek tekrarlandığında sonuç aynı kalmalıdır
• PATCH: kaynağın yalnızca belirli alanlarını günceller
• DELETE: kaynağı siler

GET ile veri değiştirmek ya da her şeyi POST ile yapmak sık görülen tasarım hatalarıdır. Güvenli ve tekrarlanabilir işlemleri doğru metotla ifade etmek, önbellekleme ve yeniden deneme davranışlarının doğru çalışması için gereklidir.

İyi bir REST API'yi ne belirler?

Kaynak adları fiil değil isimdir ve çoğul koleksiyon mantığıyla düzenlenir. Hatalar anlamlı durum kodları ve açıklayıcı mesajla dönülür. Büyük listelerde sayfalama, filtreleme ve sıralama sunulur. Arayüz değişecekse sürümleme planlanır ki mevcut istemciler bozulmasın.

Güvenlik, kimlik doğrulama ve yetkilendirme ile birlikte düşünülür; hassas veri taşıyan her istek şifreli bağlantı üzerinden yapılmalıdır. Son olarak dokümantasyon: bir API'nin gerçek kullanılabilirliğini, güncel ve örnekli bir dokümantasyon belirler. Çoğu ekip arayüzü OpenAPI gibi bir tanım biçimiyle tarif eder.

REST'in sınırları ve alternatifleri

REST, kaynak odaklı veri sunumunda sade ve yaygın bir çözümdür; fakat her ihtiyaca uymaz. İstemcinin tek istekte birden çok kaynaktan, tam istediği alanları çekmesi gerekiyorsa GraphQL daha elverişli olabilir. Servisler arası yüksek performanslı, tipli iletişimde gRPC tercih edilir. Eski kurumsal sistemlerde ise SOAP hâlâ karşımıza çıkar.

REST'in güçlü yanları anlaşılırlığı, HTTP altyapısını (önbellek, ağ geçidi, araçlar) kullanabilmesi ve geniş araç desteğidir. Bu yüzden çoğu zaman varsayılan seçimdir; alternatifler belirli bir sorunu çözmek için devreye girer.

Mindset programlarında REST API

"REST API En İyi Pratikler" programı REST temelleri ve kısıtlamalar, kaynak modelleme ve URI tasarımı, HTTP metotlarının doğru kullanımı, durum kodları ve hata yönetimi, sayfalama filtreleme ve sıralama, performans ve önbellekleme ile API test ve dokümantasyon modüllerinden oluşur. "RESTful API Tasarım Olgunluğu (Richardson Maturity)" programı kaynak modelleme, HTTP semantiği ve hipermedya konularını olgunluk seviyeleri çerçevesinde işler. "API Tasarımı ve Yönetimi" programı ise tasarım prensipleri, versiyonlama, güvenlik ve dokümantasyonu kapsar.