REST, GraphQL mi, RPC mi: API stilinin seçimi

Stil kadar zamanın ruhuna göre değerlendirilen başka bir API kararı neredeyse yoktur. Bazen biri modern, diğeri eskimiş sayılır; bazen moda yeniden tersine döner. Her iki durumda da bir uyum sorusu, bir zevk sorusu gibi tartışılır. Oysa REST, GraphQL ve RPC bir kaliteyi değil, iki sistemin birbiriyle konuşmasının üç farklı biçimini adlandırır. İşe yarar soru hangi stilin daha iyi olduğu değil, bir problemin hangi biçime sahip olduğu ve hangi stilin bu biçime uyduğudur.

Bu belge üç stili oldukları gibi ele alır: her biri belirli problemler için güçlü, diğerleri için zayıf, farklı biçimlere sahip araçlar. Protokolden ve üründen bağımsız tutulmuştur; başka yerlerde ele alınan uzun ömürlü API tasarımının ilkelerini (sözleşmeler, uyumluluk, güven sınırları) varsayar. Burada yalnızca bunlardan önce gelen karar, yani bu sözleşmenin hangi stilde biçimlendirileceği ele alınıyor. Hiçbir rakam verilmiyor.

1. Yanlış soru

“Hangi API stili en iyisidir?” yanlış bir sorudur, çünkü yalnızca duruma bağlı cevapların olduğu yerde genel bir cevap bekler. Üç stilin her biri bazı problemler için doğru seçim, diğerleri için ise dolambaçlı bir yoldur. En iyi stili arayan kişi bir moda tartışması yürütür; uygun olanı arayan ise işe yarar soruyu sorar: Burada gerçekleşecek iletişim neye benziyor? Kim kimi, ne sıklıkla ve ne amaçla çağırıyor?

Stil seçiminin neden önemli olduğu sorusunun cevabı, bu seçimin uzun ömrüdür. Stil, sistemler arasındaki sözleşmenin biçimini belirler ve bu sözleşme, her arayüz gibi, başkaları ona güvenmeye başladığı anda zor değiştirilir. Bu yüzden stili alışkanlıkla ya da modaya göre değil, bilinçli olarak ve bir nedene dayanarak seçmek en iyisidir; çünkü onunla uzun süre yaşayacaksınız. Stil seçiminden önceki soru her zaman problemin ne olduğu sorusudur.

İşi zorlaştıran bir başka etken de bir kez seçilen stilin zor değiştirilmesidir. Stil, yabancı sistemlerin güvendiği sözleşmeyi belirlediği için, stil değişikliği bir arayüzdeki her derin değişiklikle aynı yükü beraberinde getirir; çağıranlara dokunmadan tek taraflı olarak gerçekleştirilemez. Bu da ilk seçimin önemini artırır: Gelişigüzel yapılıp sonradan kolayca düzeltilebilecek bir seçim değil, uzun süre taşınacak bir seçimdir. Bu yüzden bilinçli olarak ve adı konabilecek bir nedene dayanarak yapılmasına daha da çok değer.

Ödünleşim. En iyi stil yerine uyumu sormak, genel bir önerinin rahatlığından vazgeçip kendi sisteminiz için muhakeme yapmak demektir.

Maliyet. Bu muhakeme, stili seçmeden önce kendi iletişim biçiminizi tam olarak anlamayı gerektirir; tanıdık olana uzanmaktan daha fazla emek ister.

Ne zaman farklı karar veririz. Bir ekibin bir stile derinlemesine hâkim olduğu ve problemin bu stilin biçimine uyduğu yerde uzun bir değerlendirme gereksizdir; o durumda aşinalık haklı olarak belirleyici olur.

2. Üç stili gerçekte ne ayırır

Üç stil, iletişimin neyin etrafında döndüğüne göre ayrılır. REST kaynakların etrafında döner: küçük ve sabit bir işlem kümesi üzerinden çağrılan ve değiştirilen, adı konmuş şeyler. Örnek aldığı model web'in kendi yapısıdır; gücü sadeliği ve yaygınlığıdır: Neredeyse herkes onu bilir, neredeyse her şey onu destekler. RPC eylemlerin etrafında döner: Yabancı bir sistemdeki adı konmuş bir fonksiyonu, sanki kendi fonksiyonunuzmuş gibi çağırırsınız. Gücü doğrudanlıktır: İşlemlerin yürütülmesi söz konusu olduğunda bir fonksiyonu çağırmak en doğal biçimdir.

GraphQL sorguların etrafında döner: Çağıran taraf tam olarak hangi verileri istediğini tarif eder ve tek bir istekte, birbirine bağlı pek çok şeyin üzerinden bile tam olarak bunları geri alır. Gücü, çağıran tarafın esnekliğidir: Aksi hâlde birçok çağrıyla bir araya getirmek zorunda kalacağı şeyi tek seferde alır. Bu üç biçim daha iyi ya da daha kötü değil, farklıdır: kaynakları çağırmak, eylemleri yürütmek, verileri esnek biçimde sorgulamak. Soru, kendi iletişiminizin bu biçimlerden hangisine sahip olduğudur.

Pratikte stiller arasındaki sınırlar, adların düşündürdüğü kadar keskin değildir. Kaynak odaklı bir arayüze, stile ihanet etmeden eylem benzeri birkaç çağrı ekleyebilirsiniz; aksi hâlde sade olan bir arayüzün üzerine, gerçekten gerektiği yerde esnek bir sorgu katmanı koyabilirsiniz. Üç stil birer eğilimdir, hapishane değil. Hata onları bir arada kullanmak değil, birbiriyle karıştırmaktır: bir iletişimi, yalnızca bir stile bağlanmış olduğunuz için ona uymayan bir biçimde ifade etmek.

Ödünleşim. Biçimi ciddiye almak, her iletişime tek bir stili dayatmak yerine stili iletişimin türüne göre seçmek demektir.

Maliyet. Dikkatli inceleme zaman alır ve sistemler arasında gerçekte neyin aktığının dürüstçe analiz edilmesini gerektirir.

Ne zaman farklı karar veririz. Bir sistemin birden fazla iletişim biçimi içerdiği yerde, bütünü tek bir stile sıkıştırmak yerine farklı parçalar için farklı stiller seçmek doğru olabilir.

3. REST ne zaman yeterlidir (ve bu çoğu zamandır)

En yaygın durum aynı zamanda en dikkat çekmeyenidir: Çoğu sistem için REST yeterlidir ve sadelik kolayca vazgeçilmemesi gereken bir değerdir. İletişimin özünde adı konmuş şeyleri çağırmak ve değiştirmekten ibaret olduğu yerde (ki bu, operasyonel yazılımların büyük bölümü için geçerlidir) REST akla en yatkın, yaygın ve sakin seçimdir. Her yerde anlaşılır, her yerde desteklenir, iyi önbelleklenebilir ve kolay işletilir. Sadeliği bir eksiklik değil, yıllar boyunca dayanmasının nedenidir.

Şema: Hiçbir stil başlangıç noktası değildir. İletişimin biçimi sorulur (şeyler, eylemler ya da esnek sorgular) ve seçim buna göre yapılır. Geniş orta kesim için biçim “şeyler”dir ve orada REST kazanır.

REST'in somut ve çoğu zaman hafife alınan bir avantajı önbelleklemedir. Adı konmuş bir şeyi çağırmak net ve tekrarlanabilir bir istek olduğu için, cevabı sağlayıcı ile çağıran arasındaki yolda, pek çok noktada, web'in kanıtlanmış araçlarıyla önbelleğe alınabilir. Bu, sistemin bunun için özel bir şey yapmasına gerek kalmadan kaynağın yükünü hafifletir ve çağıranı hızlandırır. İstekleri daha az öngörülebilir olan daha zengin stiller bu avantajdan büyük ölçüde vazgeçer; ancak yük altında kendini gösteren ve stiller karşılaştırılırken kolayca gözden kaçan sessiz bir bedeldir bu.

Sade REST yerine daha zengin bir stil seçmenin cazibesi büyüktür, çünkü daha modern görünür; ama REST'in problemi çözdüğü yerde daha zengin bir stil ilerleme değil, gereksiz bir karmaşıklaştırmadır. Herkesin anladığı ve zahmetsizce işletilebilen bir çözümü, ihtiyacınızdan fazlasını yapabilen ama karşılığında daha fazla emek, daha fazla işletim ve daha fazla bilgi gerektiren bir çözümle takas edersiniz. Sadeliğin yettiği yerde ondan vazgeçmek nadiren iyi bir bahistir.

Ödünleşim. REST'i seçmek, sadeliği, yaygınlığı ve sakin işletimi diğer stillerin özel esnekliğinden ya da doğrudanlığından vazgeçme karşılığında satın alır.

Maliyet. İletişimin yine de başka bir stilin biçimine sahip olduğu yerde, onu REST'te biraz daha zahmetli biçimde taklit etmeniz gerekir; sadeliğin bedeli budur.

Ne zaman farklı karar veririz. İletişimin açıkça eylemlerin ya da esnek, birbirine bağlı sorguların biçimine sahip olduğu yerde REST dolambaçlı yoldur ve uygun stil daha iyi seçimdir.

4. GraphQL ne zaman uyar ve bedeli nedir

GraphQL, çağıran taraftaki esnekliğin gerçek bir değer taşıdığı yerde doğru seçimdir: Çok sayıda farklı çağıranın, aynı ve birbirine sıkı bağlı verilerin çok farklı kesitlerine ihtiyaç duyduğu ve bu kesitleri çok sayıda tekil çağrıyla bir araya getirmenin pahalı ya da zahmetli olacağı yerde. GraphQL gücünü orada gösterir: Çağıran ihtiyacını tarif eder ve sistem tam olarak bunu, tek seferde sunar.

Şema: Bir çağıranın aksi hâlde birbirine bağlı pek çok şeyi tek tek bir araya getirdiği yerde, esnek bir sorgu tam olarak isteneni tek seferde getirir. GraphQL'in durumu budur ve bedeline yalnızca orada değer.

Bu esnekliğin, seçim anında kolayca gözden kaçan bir bedeli vardır. Çağıranın özgürlüğü karmaşıklığı sağlayıcı tarafına kaydırır: İstekleri öngörmek, önbelleklemek ve kötüye kullanıma karşı korumak zorlaşır, çünkü çağıranın ne isteyeceğini artık bilemezsiniz. İşletim daha zahmetli hâle gelir ve sistem, REST'in ihtiyaç duymadığı önlemlere ihtiyaç duyar. Bu yüzden GraphQL, REST'in yerini alan bir şey değil, belirli bir durum (birbirine bağlı veriler üzerinde çok çeşitli veri ihtiyacı) için doğru seçim, diğer tüm durumlar için ise pahalı bir dolambaçtır.

Ödünleşim. GraphQL, çağıran için esnekliği sağlayıcı tarafında kaydırılmış karmaşıklık, zorlaşan önbellekleme ve daha zahmetli işletim karşılığında satın alır.

Maliyet. İsteğin özgürlüğü, öngörülemezliğe ve kötüye kullanıma karşı inşa edilip bakımı yapılması gereken ek önlemler gerektirir.

Ne zaman farklı karar veririz. Veri ihtiyacının basit ve öngörülebilir olduğu yerde GraphQL'in esnekliği kullanılmadan kalır ve yalnızca bedeli taşınır; o durumda daha sade stil üstündür.

5. RPC ne zaman en net biçimdir

RPC, iletişimin özünde şeyleri çağırmaktan değil, eylemleri yürütmekten oluştuğu yerde doğru seçimdir. Bir sistemin diğerinden bir şey yapmasını istediği yerde (bir hesaplamayı başlatmak, bir süreci tetiklemek, bir işlemi gerçekleştirmek) adı konmuş bir fonksiyonu doğrudan çağırmak en dürüst biçimdir. Eylemi, kendini doğal olmayan bir şekilde ifade ettiği kaynak diline çevirmeniz gerekmez; onu olduğu şey olarak adlandırırsınız. Özellikle aynı sistemin servisleri arasındaki iletişimde, doğrudanlığın ve verimliliğin önemli olduğu ve yabancı bir kitleye hizmet edilmediği yerde, RPC çoğu zaman en sade ve en net seçimdir. Orada daha sıkı bağlılığı pek ağır basmaz, çünkü ilgili servisler zaten birbirine aittir ve birlikte geliştirilir.

RPC'nin bedeli, doğrudanlığının öbür yüzüdür. Çağrılan fonksiyona daha sıkı bağladığı için sistemler arasındaki bağlılık genellikle daha güçlüdür ve stil, yabancı çağıranlar için yaygın REST kadar kendini açıklayıcı değildir. Herkese açık ve geniş çapta kullanılan bir arayüz için bu bir dezavantajdır; birbirine ait servisler arasındaki dahili iletişim için ise daha sıkı bağlılık çoğu zaman önemsizdir ve doğrudanlık bir kazançtır. Diğer stillerde olduğu gibi bağlam belirleyicidir: RPC, eylemlerin ön planda olduğu ve çağıranların bilindiği yerde parlar.

Ödünleşim. RPC, eylemleri yürütmede doğrudanlığı genellikle daha sıkı bir bağlılık ve yabancı çağıranlar için daha düşük kendini açıklama karşılığında satın alır.

Maliyet. Çağrılan fonksiyona daha sıkı bağlanma, özellikle çağıranlar arasında yakın bir koordinasyon yoksa, arayüzdeki değişiklikleri daha hissedilir kılabilir.

Ne zaman farklı karar veririz. Çok sayıda bilinmeyen çağıranı olan herkese açık bir arayüz için REST'in yaygınlığı ve kendini açıklayıcılığı genellikle RPC'nin doğrudanlığından daha değerlidir.

6. Ölçüt: iletişimin biçimi

Üç yolun tamamı tek bir ölçütte birleşir: gerçekleşecek iletişimin biçimi. Her şey çağrılan ve değiştirilen, adı konmuş şeylerin etrafında dönüyorsa REST doğal seçimdir. Bilinen sistemler arasında eylemlerin yürütülmesi söz konusuysa RPC en net biçimdir. Çok sayıda farklı çağıran, birbirine sıkı bağlı verilerin esnek kesitlerine ihtiyaç duyuyorsa GraphQL avantajlıdır. Ölçüt moda değil, kimin kime nasıl ve ne amaçla hitap ettiği sorusudur.

İletişimin biçimine çoğu zaman hafife alınan ikinci bir büyüklük eklenir: ekibin neye hâkim olduğu ve çağıranların ne beklediği. Pek çok kişinin bildiği bir stil, bir sistemi yıllarca işletmenin ve arayüzünü yabancı geliştiricilere kullandırmanın maliyetini düşürür. Daha zengin ve daha nadir bir stil her iki tarafta da daha fazla bilgi gerektirir: onu işleten sağlayıcıda ve onu kullanan çağıranda. Bu bilgi maliyetleri gerçek ve kalıcıdır; problemin biçimi açıkça başka bir stil gerektirmedikçe, şüphe durumunda yaygın stilden yana ağır basarlar.

Ömür bu ölçüte bir ihtiyat daha ekler: Stil sözleşmeyi belirlediği ve sözleşmenin değiştirilmesi zor olduğu için, şüphe durumunda on yıl sonra hâlâ anlaşılabilecek ve onun için ekip bulunabilecek daha sade ve daha yaygın stil seçilir. Daha zengin bir stil, ek emeğini sistemin ömrü boyunca haklı çıkarmalıdır; çıkaramıyorsa sadelik daha uzun ömürlü seçimdir. İletişimin biçimine ve ömre göre karar veren kişi, stili ne modaya karşı savunmak ne de ona uymak zorunda kalır; işin kendisine göre karar verir.

Ödünleşim. İletişimin biçimine göre karar vermek, tanıdık ya da modaya uygun stili izlemek yerine bu biçimi dürüstçe adlandırmayı gerektirir.

Maliyet. Bu ölçüt, her şey için rahat bir şirket kuralı yerine her arayüz için ayrımlı bir cevabı zorunlu kılar.

Ne zaman farklı karar veririz. Stili harici bir zorunluluğun belirlediği yerde (talep edilen bir uyumluluk, mevcut bir sistem ortamı) ölçüt geri planda kalır ve zorunluluğa uyulur.

7. Tipik hatalar

Stil seçiminin başarısız olduğu tekrar eden örüntüler; neredeyse hepsi biçime göre değil modaya göre karar vermenin farklı biçimleridir:

• Stili zamanın ruhuna göre seçmek ve bir uyum sorusunu bir zevk sorusu gibi tartışmak.
• REST'i eskimiş saymak ve sadeliğin yeteceği yerde daha zengin bir stil seçmek.
• GraphQL'in esnekliğini, onu haklı çıkaracak çok çeşitli veri ihtiyacı olmadan seçmek ve yalnızca bedelini taşımak.
• GraphQL'in kaydırdığı karmaşıklığı gözden kaçırmak: zorlaşan önbellekleme, daha zahmetli işletim, öngörülemezliğe karşı koruma.
• Doğrudan bir çağrının daha dürüst biçim olacağı yerde eylemleri kaynak diline zorlamak.
• Yaygınlığın ve kendini açıklamanın daha önemli olduğu, çok sayıda bilinmeyen çağıranı olan herkese açık bir arayüz için RPC'yi seçmek.
• Farklı parçalar farklı iletişim biçimlerine sahip olduğu hâlde tüm sistemi tek bir stile sıkıştırmak.
• Stilin uzun ömrünü gözden kaçırmak ve yıllar sonra zor anlaşılacak ya da onun için zor ekip bulunacak bir stil seçmek.

8. Karar kontrol listesi

API stilini seçmeden önce sırasıyla netleştirilmesi gerekenler:

• İletişimin biçimi? Her şey şeylerin (REST), eylemlerin (RPC) ya da birbirine bağlı verilerin esnek sorgularının (GraphQL) etrafında mı dönüyor?
• REST yeterli mi? En sade ve en yaygın stil problemi çözüyor mu ve daha zengin bir stil gerçekten gerekli mi?
• Esneklik gerekli mi? GraphQL için: Birbirine bağlı verilere çok farklı ihtiyaçlar duyan çok sayıda çağıran var mı, yoksa esneklik kullanılmadan mı kalacak?
• Gizli maliyetler düşünüldü mü? GraphQL'de zorlaşan önbellekleme ve daha zahmetli işletim, RPC'de ise daha sıkı bağlılık hesaba katıldı mı?
• Herkese açık mı, dahili mi? Arayüz çok sayıda bilinmeyen çağırana mı (daha çok REST), yoksa bilinen ve birbirine ait servislere mi (RPC savunulabilir) hizmet ediyor?
• Karma sistem mi? Her şey için tek bir stil yerine farklı parçaların farklı stilleri hak edip etmediği incelendi mi?
• Uzun ömür? Stil, yıllarca anlaşılabilecek ve onun için ekip bulunabilecek bir stil mi ve daha zengin bir stil ek emeğini haklı çıkarıyor mu?

Bu soruları cevaplayabilen kişi API stilini, o an modern sayılan şeye göre değil, iletişimin biçimine göre seçmiş olur.

Sıkça Sorulan Sorular

GraphQL, REST'in modern halefi mi? Hayır, farklı bir durum için farklı bir biçimdir. GraphQL, çok sayıda çağıranın birbirine sıkı bağlı verilerin esnek kesitlerine ihtiyaç duyduğu yerde parlar; REST ise adı konmuş şeylerin sade biçimde çağrılması ve değiştirilmesi söz konusu olduğunda parlar. Biri diğerinin yerini almaz; farklı iletişim biçimlerine uyarlar. En yaygın durum için REST yeterlidir.

REST neden çoğu sistem için doğru seçimdir? Çünkü operasyonel iletişimin büyük bölümü özünde adı konmuş şeyleri çağırmaktan ve değiştirmekten ibarettir; tam olarak REST'in biçimi. REST her yerde anlaşılır, iyi önbelleklenebilir ve kolay işletilir. Sadeliği bir eksiklik değil, yıllar boyunca dayanmasının nedenidir. Yettiği yerde daha zengin bir stil gereksiz bir karmaşıklaştırmadır.

GraphQL'in kolayca gözden kaçan bedeli nedir? Çağıranın esnekliği karmaşıklığı sağlayıcıya kaydırır: İstekleri öngörmek, önbelleklemek ve kötüye kullanıma karşı korumak zorlaşır. İşletim daha zahmetli hâle gelir. Bu maliyetler, çok çeşitli veri ihtiyacının onları haklı çıkardığı yerde iyi bir yatırımdır; bu ihtiyacın olmadığı yerde ise israftır.

RPC ne zaman doğru seçimdir? İletişimin şeyleri çağırmaktan değil eylemleri yürütmekten oluştuğu yerde; özellikle aynı sistemin servisleri arasında, doğrudanlığın önemli olduğu ve yabancı bir kitleye hizmet edilmediği durumlarda. Bir eylemi adı konmuş bir fonksiyon çağrısı olarak ifade etmek, onu kaynak diline zorlamaktan daha dürüsttür. Herkese açık arayüzler için REST genellikle daha iyi seçimdir.

Bir sistemde birden fazla stil kullanabilir miyiz? Evet ve bu çoğu zaman doğrudur. Bir sistemin farklı parçaları farklı iletişim biçimlerine sahiptir; dahili servisler birbirleriyle, herkese açık bir arayüzün çağıranlarıyla konuştuğundan farklı konuşur. Bir parça ihtiyaç duyduğu için tüm sistemi tek bir stile sıkıştırmak, diğer parçalara kendilerine ait olmayan bir biçim dayatır.

Uzun ömürlü bir sistem için nasıl seçim yaparım? Şüphe durumunda, on yıl sonra hâlâ anlaşılabilecek ve onun için ekip bulunabilecek daha sade ve daha yaygın stili seçersiniz. Stil zor değiştirilen sözleşmeyi belirlediği için, daha zengin bir stil ek emeğini sistemin ömrü boyunca haklı çıkarmalıdır. Çıkaramıyorsa sadelik daha uzun ömürlü seçimdir.

İleri okuma

• Uzun ömürlü sistemler için API tasarımı: Seçilen stilden bağımsız olarak sözleşmenin ilkeleri.
• Müşterileri bozmadan API sürümlendirme: Stil ne olursa olsun sözleşme nasıl geliştirilir.
• Yenilik yerine olgun teknoloji: Yaygın ve sade stilin neden çoğu zaman daha uzun ömürlü seçim olduğu.
• Sunucu tarafı render mı, SPA mı: Aynı sıklıkla uyuma göre değil modaya göre verilen, benzer bir karar.

Temelinde Batunet Engineering Method yatar: iletişimin biçimine göre karar vermek, taşıyabilen en sade seçeneği seçmek, modayı değil ihtiyacı izlemek.

Son mühendislik ilkesi

API stili bir inanç beyanı değil, iletişimin biçimine yapılan bir uyarlamadır. REST, GraphQL ve RPC üç farklı soruya verilmiş üç cevaptır (şeyleri çağırmak, eylemleri yürütmek, verileri esnek biçimde sorgulamak) ve ustalık, cevabı seçmeden önce kendi sorunuzu tanımaktadır. Operasyonel sistemlerin geniş orta kesimi için soru “şeyleri çağırmak ve değiştirmek”tir ve orada sade, yaygın cevap aynı zamanda en uzun ömürlü olandır. Daha modern göründüğü için daha zengin bir stil seçmenin cazibesi, teknoloji seçiminde de direnilen cazibenin aynısıdır: En heyecan verici olan değil, en uygun olan seçilir ve en uygun olan, zamanın ruhunun inandırmak istediğinden daha sık sade olandır. Stili iletişimin biçimine ve ömre göre seçen kişi, aksi hâlde onu belirleyecek olan modalar çoktan değiştiğinde hâlâ dayanan ve hâlâ anlaşılan bir arayüze sahip olur.

Hiçbir API stili modern ya da eskimiş değildir; her biri belirli bir soru biçiminin cevabıdır. Kendi sorusunu bilen kişinin modaya ihtiyacı yoktur.