GraphQL, "bana şu alanları ver" diyebildiğiniz bir sorgu dilidir. GraphQL'in resmî anlatımına göre istemci, sunucudan tam olarak ihtiyaç duyduğu veriyi ister ve fazlasını almaz. REST'te her kaynak ayrı adrestedir; GraphQL'de ise çoğunlukla tek bir adres vardır ve ne istendiği sorgunun içinde yazılır.
Sorgu ve mutation
| Tür | Ne yapar | Örnek kullanım |
|---|---|---|
| Query | Veri okur | Ürün listesini yalnız ad, SKU ve stok alanlarıyla almak |
| Mutation | Veri değiştirir | Bir varyantın stok adedini güncellemek |
Sorgu iç içe yazılabilir. Örneğin ürünleri, her ürünün varyantlarını ve her varyantın stok bilgisini tek istekte almak mümkündür. REST'te bu iş birkaç ayrı istek gerektirebilir.
Pazaryeri örneği: ikas
ikas yönetim API'si GraphQL ile çalışır. Saystok'un ikas bağlantısı tüm sorguları https://api.myikas.com/api/v1/admin/graphql adresine gönderir. Kimlik için önce mağazaya özel adresten OAuth 2.0 client credentials ile belirteç alınır, sorgular "Bearer" başlığıyla yapılır. Ürün görselleri gibi bazı işler ise ayrı bir REST ucundan yüklenir.
Shopify'ın yönetim API'sinin de GraphQL sürümü vardır. Saystok'un Shopify bağlantısı ise şu an Shopify'ın REST yönetim API'sini kullanır.
Hata yapısı farklıdır
GraphQL'de bir sorgu kısmen başarısız olsa bile HTTP yanıtı 200 dönebilir. Hata ayrıntısı yanıt gövdesindeki errors alanında gelir. Yalnız HTTP koduna bakan bir kod bu hatayı kaçırır. Bu yüzden GraphQL entegrasyonunda her yanıtta errors alanı ayrıca kontrol edilir.
Avantaj ve dezavantaj
- Avantaj: Gereksiz veri taşınmaz; mobil ve yoğun entegrasyonlarda bant genişliği azalır.
- Avantaj: Şema kendini tanımlar; araçlar mevcut alanları otomatik listeler.
- Dezavantaj: Karmaşık sorgular sunucuya yük bindirir. Bu yüzden platformlar istek sayısı yerine sorgu maliyetiyle sınır koyabilir.
- Dezavantaj: Önbellekleme REST'e göre zordur.
Diğer API tarzları için REST API ve SOAP maddelerine bakın.