GraphQL Nedir?
Kısa tanım
GraphQL, API'ler için geliştirilmiş bir sorgu dili ve bu sorguları çalıştıran sunucu tarafı için tanımlanmış bir spesifikasyondur. İstemci, genellikle tek bir uç noktaya ihtiyaç duyduğu alanları tarif eden bir sorgu gönderir ve yanıtı tam olarak o biçimde alır. Bütün veri türleri güçlü tipli bir şemada tanımlanır. Facebook'ta geliştirilen GraphQL bugün Linux Foundation bünyesindeki GraphQL Foundation tarafından yönetilir.
Diğer adları: GraphQL API, GraphQL sorgu dili, GQL
İstemci ne istediğini kendisi tarif eder
Klasik bir REST API'de her kaynağın kendi URL'si vardır ve yanıtın biçimini sunucu belirler. GraphQL'de ise sunucu bütün veriyi tipleriyle birlikte bir şemada tanımlar; istemci bu şemadan hangi alanlara ihtiyacı olduğunu bir sorguyla söyler. Sorgular genellikle /graphql gibi tek bir uç noktaya gönderilir ve yanıt, sorgunun şeklini birebir izleyen bir JSON belgesidir.
query {
musteri(id: "42") {
ad
sonSiparisler(adet: 3) {
numara
tutar
}
}
}{
"data": {
"musteri": {
"ad": "Ayşe Yılmaz",
"sonSiparisler": [
{ "numara": "S-1042", "tutar": 1499.9 },
{ "numara": "S-1017", "tutar": 320 },
{ "numara": "S-0988", "tutar": 75.5 }
]
}
}
}Over-fetching ve under-fetching
GraphQL'in çözdüğü iki sorunun adı Türkçe ekiplerde de genellikle İngilizce kullanılır. Over-fetching, ihtiyaçtan fazla veri almaktır: mobil uygulamanın müşteri kartında yalnızca ad gerekirken /musteriler/42 yanıtı kırk alan döndürür. Under-fetching ise tek istekle yeterli veriyi alamamaktır: müşteriyi aldıktan sonra son siparişler için ikinci, her siparişin kargo durumu için üçüncü bir istek gerekir. Yavaş mobil ağlarda bu ardışık istekler toplam bekleme süresini belirgin biçimde uzatır. GraphQL'de aynı ekran tek bir sorguyla ve yalnızca gereken alanlarla beslenir.
Şema, resolver ve işlem türleri
Şema, hangi tiplerin ve alanların var olduğunu, hangi alanın zorunlu olduğunu ve neyin hangi argümanları aldığını tanımlar. Her alanın arkasında, değeri nereden getireceğini bilen bir resolver fonksiyonu bulunur; bu bir veritabanı sorgusu, başka bir REST servisi ya da önbellek olabilir. GraphQL bu yüzden bir veritabanı dili değildir, veri kaynaklarından bağımsız bir arayüz katmanıdır. Üç işlem türü vardır: veri okuyan query, veri değiştiren mutation ve gerçek zamanlı güncellemeler için subscription. Şema, introspection özelliği sayesinde istemciler tarafından sorgulanabilir; geliştirici araçlarındaki otomatik tamamlama buna dayanır.
HTTP üzerinde nasıl taşınır?
Yaygın yöntem, sorguyu application/json gövdesiyle POST isteği olarak göndermektir. Gövdede query alanı zorunludur; variables ve operationName isteğe bağlıdır. Yalnızca okuma yapan sorgular GET ile de gönderilebilir; değişiklik yapan işlemler gönderilemez. Yanıtta data ve hata varsa errors alanları bulunur. REST'ten farklı olarak kısmi hatalar mümkündür: bazı alanlar gelirken bazıları hata verebilir ve HTTP durumu yine 2xx olabilir. Ayrıntılar resmî GraphQL over HTTP rehberinde yer alıyor.
Esnekliğin bedeli
- Önbellek: Her şey tek bir URL'ye
POSTolarak gittiği için tarayıcı ve CDN düzeyindeki HTTP önbelleklemesi REST'teki kadar kendiliğinden işlemez; istemci tarafı önbellek kütüphaneleri veya kalıcı sorgular (persisted queries) gerekir. - N+1 sorgu: Liste içindeki her öğe için ayrı veritabanı sorgusu atılabilir; istekleri toplayan DataLoader benzeri bir katman şarttır.
- Kötüye kullanım: İstemci sorguyu serbestçe yazabildiği için derinlik ve karmaşıklık sınırları, sorgu maliyetine göre hız sınırlama ve alan düzeyinde yetki kontrolü kurulmalıdır.
Farklı ekranların farklı veri şekilleri istediği, çok istemcili ürünlerde GraphQL güçlüdür. Az sayıda, iyi tanımlı kaynağı olan ve herkese açık önbelleklenebilir yanıtlar sunan servislerde REST çoğu zaman daha sade bir çözümdür.