Yeni Başlayanlar İçin GraphQL Rehberi

Bugün en çok tartışılan terimlerden biri API’dır. Pek çok insan bir API’nin tam olarak ne olduğunu bilmiyor. Temel olarak API, Uygulama Programlama Arayüzü anlamına gelir. Adından da anlaşılacağı gibi, insanların; geliştiricilerin, kullanıcıların, tüketicilerin vb. verilerle etkileşime girebileceği bir arayüzdür. API’yi mağazada çalışan görevli olarak düşünebilirsiniz. Bu görevliden bir ürün istersiniz ve size istediğinizi verir. Eğer API bu kadar basit bir yapıdaysa, problem nerede peki?

Modern web’in başlangıcından bu yana, API oluşturmak göründüğü kadar zor olmamıştı. Ancak API’leri öğrenmek ve anlamak için durum pekte öyle değildi. Bu yüzden bu yazımızda, API ve GraphQL konularında anlatmak istediklerimi sizlerle paylaşacağım. Bu konuya elimden geldiğince ışık tutmaya çalışacağım.

Geliştiriciler, API’nizi bir şeyler oluşturmak veya yalnızca veri tüketmek için kullanacak kişilerin çoğunluğunu oluştururlar. Dolayısıyla, API’niz olabildiğince temiz ve anlaşılır olmalıdır. İyi tasarlanmış bir API’nin kullanımı ve öğrenilmesi çok kolaydır.

API’leri oluşturmak için uzun süredir REST kullanıyoruz. Bununla birlikte bazı sorunlar da ortaya çıkıyor. Sizler de REST tasarımını kullanarak bir API oluştururken aşağıdaki gibi bazı sorunlarla karşılaşacaksınız:

  1. Çok sayıda uç noktanız olacak.
  2. Geliştiricilerin API’nizi öğrenmesi ve anlaması çok daha zor olacak.
  3. Bu konuda büyük bir bilgi karmaşası var.

Tüm bu sorunların çözüme kavuşması için Facebook harika bir adım attı ve Facebook GraphQL‘i yarattı. GraphQL’in API oluşturmanın en iyi yollarından biri olduğunu düşünüyorum. Aslında bu makale biraz da sizi GraphQL öğrenme konusunda teşvik etmek üzerine olacak. Çünkü bu teknoloji ile çok iyi işler çıkarmanız mümkün.

Bu makalede, GraphQL’in nasıl çalıştığını öğreneceksiniz. GraphQL kullanarak çok iyi tasarlanmış, verimli ve güçlü bir API’nin nasıl oluşturulacağını size göstermeye çalışacağım. Muhtemelen birçok kişi ve şirket tarafından kullanıldığı için GraphQL’i zaten duymuşsunuzdur. GraphQL, açık kaynak kodlu olduğu için yardım alabileceğiniz büyük bir topluluğu var. Küçük bir internet araştırmasıyla bu topluluklara ulaşmanız mümkün. Şimdi vakit kaybetmeden GraphQL’in sihrini hep beraber görmeye çalışalım.

GraphQL Nedir?

GraphQL, Facebook tarafından geliştirilen açık kaynaklı bir sorgu dilidir. Bize API’lerimizi tasarlama, oluşturma ve kullanma konusunda daha verimli bir yol sağlar. Aslında temel olarak, az önce bahsettiğimiz REST’in yerini alıyor.

GraphQL, aşağıdakiler gibi daha birçok özelliğe sahip:

  1. İstediğiniz verileri yazarsınız ve tam olarak istediğiniz verileri alırsınız.
  2. Bize tek bir uç nokta veriyor, yani aynı API için sürüm 2 veya sürüm 3 yok.
  3. GraphQL güçlü bir şekilde yazılmıştır. Daha güçlü API’ler oluşturmamıza yardımcı olur.

Başlangıç

Bu makalede asıl bahsedeceğimiz konu, GraphQL sunucusunun nasıl kurulacağını öğrenmek değil. Bu yüzden bu konuya derinlemesine girmemizin bir nedeni yok. Amacımız, GraphQL’in pratikte nasıl çalıştığını gözlemlemek. Bu nedenle Graphpack isimli bir GraphQL sunucusunu kullanacağız.

Elbette projemize başlamak için yeni bir klasör oluşturacağız. Buna istediğiniz ismi verebilirsiniz. Ben graphql-server adını vereceğim. Daha sonra komut ekranınızı yada terminalinizi açın ve şunları yazın:

Panoya Kopyala!

Şimdi kullandığınız bilgisayara npm veya yarn kurmanız gerekiyor. Eğer bunlar ne bilmiyorsanız, npm ve yarn JavaScript programlama dili için paket yöneticileridir. Node.js için varsayılan paket yönetici npm‘dir.

Az önce oluşturduğunuz klasörünüzde sağa tıklayıp, “Git Bash Here” seçeneği ile yada “Komut penceresi” ile aşağıdaki satırı ekleyin:

Panoya Kopyala!

Eğer yarn kullanıyorsanız, buradaki kodu girmelisiniz:

Panoya Kopyala!

Tüm bunlardan sonra npm, sizin için package.json isimli bir dosya oluşturacak. Tüm komutlarınız bu dosya içerisinde yer alacak. Şimdi size linkini verdiğim Graphpack’i kurmaya geçelim.

Graphpack, sıfır yapılandırma ile bir GraphQL sunucusu kurmanıza izin verir. GraphQL yolculuğumuza daha yeni başladığımız için, Graphpack, sunucu yapılandırması hakkında endişelenmeden devam etmemize ve daha fazlasını öğrenmemize yardımcı olacaktır.

Şimdi komut pencerenizde yada terminalinizde, kök klasörünüzün içine kurulumu şu kodlarla yapabilirsiniz:

Panoya Kopyala!

Eğer yarn kullanıyorsanız:

Panoya Kopyala!

Graphpack yüklendikten sonra, klasörünüze gidin ve daha önceden oluşturduğumuz package.json içerisine aşağıdaki kodu girin:

Panoya Kopyala!

Şimdi ise, src isimli bir klasör oluşturacağız ve sunucumuzdaki tek klasör bu olacak. Bu src dosyasının içine üç adet daha dosya oluşturmamız gerekecek. Öncelikle src klasörünün içine schema.graphql isminde bir dosya oluşturmalıyız. Bu ilk dosyamızın schema.graphql içine aşağıdaki kodu girin:

Panoya Kopyala!

schema.graphql dosyasında bizim tüm GraphQL şemamız yer alacak. Ne olduğu konusunda bir fikriniz yoksa endişelenmeyin çünkü hepsini açıklayacağım.

Şimdi src klasörümüzün içine ikinci dosyamızı oluşturalım. Adı da resolver.js olsun. Aşağıdaki kodu resolver.js dosyamıza yazalım:

Panoya Kopyala!

resolver.js isimli bu dosyamız ile, bir GraphQL işlemini verilere dönüştürebilecek talimatları sağlayacağız.

Ve en son olarak, src klasörü içerisinde son bir dosya daha oluşturalım. Bu arkadaşımızın adı ise db.js olacak. Bu üçüncü db.js dosyamızın içine ise aşağıdaki kodu yazacağız:

Panoya Kopyala!

Bu eğitimde gerçek dünya veritabanı kullanmıyoruz. Yani bu db.js dosyası, sadece öğrenme amacıyla bir veritabanını simüle edecek. Tüm bu işlemlerden sonra src klasörünüz şu şekilde görünmeli:

Şimdi, sizinle alakalı olan komutu çalıştırırsanız; npm run dev veya yarn için, yarn dev, eğer her şey yolunda gidiyorsa şu çıktıyı görmelisiniz:

Bu, GraphQL’de ilk sorgularımızı ve aboneliklerimizi yazmaya başlamak için hazır olduğumuz anlamına geliyor.

Artık localhost:4000 adresine giderek, ilk işlemlerinizi yapmaya başlayabileceksiniz.

Daha iyi geliştirme imkanları için güçlü bir GraphQL IDE olan GraphQL Playground’ı incelemenizi tavsiye ederim. GraphQL Playground hakkında daha fazla bilgi edinmek istiyorsanız, buraya tıklayın.

Şema (Schema)

GraphQL, şema yazmak için kendi dil türüne sahiptir. Bu, Şema Tanımlama Dili (SDL – Schema Definition Language) adı verilen, biz insanlar tarafından okunabilen bir şema sözdizimidir. SDL, hangi teknolojiyi kullanırsanız kullanın aynı olacaktır (bunu istediğiniz herhangi bir dil veya çerçeve ile kullanabilirsiniz).

Türler (Types)

Türler, GraphQL’in en önemli özelliklerinden biri ve API’nizin nasıl görüneceğini temsil eden özel nesnelerdir. Örneğin, bir sosyal medya uygulaması oluşturuyorsanız, API’nizin Gönderiler, Kullanıcılar, Beğeniler, Gruplar gibi türleri olmalıdır.

Türlerin alanları vardır ve bu alanlar belirli bir veri türü döndürürler. Örneğin, bir Kullanıcı türü oluşturacağız. Bunun için; ad, e-posta ve yaş alanlarımız olmalı. Tür alanları herhangi bir şey olabilirler ve her zaman Int, Float, String, Boolean, ID veya Özel Nesne Türleri gibi bir veri türü döndürürler.

Şimdi ilk Türünüzü (Type) yazmak için, schema.graphql isimli dosyanıza gidin ve zaten var olan “Sorgu türünü” aşağıdakilerle değiştirin:

Panoya Kopyala!

Her Kullanıcının bir ID’si olacağı için burada bir ID türü verdik. Ayrıca kullanıcının bir adı ve e-postası olacak, bu yüzden String ve yaşını girmesi için Int türünü kullandık. Peki ya ünlem işaretleri ne anlama geliyorlar? Ünlem işareti, alanların boş değer atanamaz olduğu anlamına gelir; bu, her alanın her sorguda bazı veriler döndürmesi gerektiği anlamına gelir. Kullanıcı tipimizde sahip olacağımız tek boş alan yaş olacaktır.

GraphQL’de üç ana kavramla ilgileneceksiniz:

  1. Sorgular – sunucudan veri alma şekliniz.
  2. Mutasyonlar – sunucudaki verileri değiştirme ve güncellenmiş verileri geri alma (oluşturma, güncelleme, silme) yolunuz
  3. Abonelikler – sunucuyla gerçek zamanlı bağlantı kurmanın yolu.

GraphQL’de Sorgular

Bunu basit bir şekilde açıklamak gerekirse, GraphQL’deki sorgular verileri nasıl elde edeceğinizdir. GraphQL’deki sorgularla ilgili en güzel şeylerden biri, istediğiniz veriyi tam olarak elde edecek olmanızdır. Ne eksik ne fazla. Bunun API’mizde çok büyük bir olumlu etkisi var. REST API‘lerde olduğu gibi artık fazla veya yetersiz bilgi getirme gibi durumlar yok.

O halde beraber GraphQL’de ilk tür sorgumuzu oluşturalım ve konuyu daha iyi anlamaya çalışalım. Tüm sorgularımız bu tür içinde sonuçlanacaktır. Bu yüzden başlamak için, gidip schema.graphql dosyamızı açın ve Sorgu (Query) adında yeni bir tür yazmaya başlayalım:

Panoya Kopyala!

Çok basit! Kullanıcıların sorgusu bize bir veya daha fazla Kullanıcı dizisi döndürecektir. Ama asla boş dönmeyecek. Çünkü “!” işaretimizi unutmayalım. Ünlem işaretimiz bunun boş geçilemeyecek (null) bir sorgu olduğunu belirtecek ve her zaman bir şey döndürülmesini sağlayacaktır.

Ancak bunu belirli bir kullanıcıyı da iade edebiliriz. Bunun için kullanıcı adında yeni bir sorgu oluşturacağız. Bunun için sorgu tipimizin içine aşağıdaki kodu girin:

Panoya Kopyala!

Şimdi Sorgu tipimiz şu şekilde görünmelidir:

Gördüğünüz gibi, GraphQL’deki sorgularla bazı argümanları da iletebiliriz. Bu örnekte, belirli bir kullanıcıyı sorgulamak için kimliğini ilettik. Ama belki merak ediyor olabilirsiniz: GraphQL verileri nereden aldığını nasıl biliyor? Ben bunu oldukça merak etmiştim. Bu yüzden bir resolvers.js dosyamız olmalı. Bu dosya GraphQL’e verileri nasıl ve nereden alacağını söyler.

Önce resolvers.js dosyamıza gidin. Daha önce bunu oluşturmuştuk. Ardından yine daha önce oluşturduğumuz db.js dosyasını içe aktarın. Bu işlemler sonucunda resolver.js dosyası şu şekilde görünecektir:

Panoya Kopyala!

Şimdi ilk sorgumuzu oluşturalım ve bu dosyamızda biraz değişiklikler yapalım:

Bu kod satırlarını biraz açıklamak istiyorum. Her sorgu çözümleyicinin dört bağımsız değişkeni vardır. Kullanıcı işlevinde, id’yi bir argüman olarak ileteceğiz ve sonra geçen id ile eşleşen, belirli bir kullanıcıyı döndüreceğiz. Oldukça kolay. Sadece basit düşünmeye çalışın. Kullanıcılar işlevinde, zaten var olan kullanıcılar dizisini döndüreceğiz. Bu her zaman tüm kullanıcılarımıza geri dönecektir.

Şimdi, sorgularımızın iyi çalışıp çalışmadığını test edelim. localhost:4000‘e gidin ve bu kodları girin:

Bu şekilde, tüm kullanıcılarımıza geri dönmelidir. Ancak belirli bir kullanıcıyı döndürmek istersek:

Yukarıdaki gibi bir kullanıma başvurabiliriz.

GraphQL’de Mutasyonlar

GraphQL’de mutasyonlar; sunucudaki verileri değiştirmenin ve güncellenmiş verileri geri alma yoludur. Bunu REST‘deki CUD(Oluştur, Güncelle, Sil) gibi düşünebilirsiniz.

İlk tip mutasyonumuzu GraphQL’de yaratacağız ve tüm mutasyonlarımız bu tipte sonlanacak. Şimdi başlamak için, schema.graphql dosyamıza gidin ve mutasyon adı verilen yeni bir tür için şu kodları yazmaya başlayın:

Gördüğünüz gibi, toplamda üç mutasyonumuz olacak:

  • createUser : Bir kimlik, isim, e-posta ve yaş girilmeli. Bize yeni bir kullanıcı döndürmeli.
  • updateUser : Bir kimlik ve yeni bir ad, e-posta veya yaş girilmei. Bize yeni bir kullanıcı döndürmeli.
  • deleteUser : Bir kimlik girmeli ve silinen kullanıcıyı döndürmeli.

Şimdi resolvers.js dosyamıza gidin ve Sorgu nesnesinin altında, aşağıdaki gibi yeni bir mutasyon nesnesi oluşturun:

Panoya Kopyala!

Artık, resolvers.js dosyamız şöyle görünmeli:

Şimdi, mutasyonlarımızın iyi çalışıp çalışmadığını test edelim. localhost:4000‘e gidin ve aşağıdaki kodu girin:

Panoya Kopyala!

Böylece bu, size yeni bir kullanıcı vermelidir. Yeni mutasyonlar yapmayı denemek istiyorsanız, kendiniz denemenizi tavsiye ederim! İyi çalışıp çalışmadığını görmek için oluşturduğunuz aynı kullanıcıyı silmeyi deneyin. Çeşitli testler yapın ve deneme yanılma yöntemiyle öğrenmeye inanın. Bu şekilde tüm kitaplardan ve blog yazılarından çok daha fazlasını öğrenebileceğinize adım gibi eminim.

GraphQL’de Abonelikler

Abonelikler, bir sunucuyla gerçek zamanlı bağlantı kurmanın yoludur. Bu, sunucuda bir olay meydana geldiğinde ve bu olay çağrıldığında, sunucunun ilgili verileri istemciye göndereceği anlamına gelir.

Aboneliklerle çalışarak, uygulamanızı farklı kullanıcılar arasında, en son değişikliklere göre güncel tutabilirsiniz.

Temel bir abonelik şu şekildedir:

Eğer “Sorguya” benzediğini düşünüyorsanız, haksız değilsiniz. Kesinlikle öyle. Ama elbette farklı çalışıyorlar. Sunucuda bir şey güncellendiğinde, sunucu, abonelikte belirtilen GraphQL sorgusunu çalıştıracak ve istemciye yeni güncellenmiş bir sonuç gönderecektir.

Bu yazımızda “Abonelikler” konusuna uzun uzun değinmeyeceğiz. Ama eğer okumaya devam etmek isterseniz buradan “Abonelikler” ile ilgili bilgi alabilirsiniz.

Sonuç olarak, gördüğünüz gibi GraphQL gerçekten güçlü olan bir teknoloji. Bize daha iyi ve iyi tasarlanmış API’ler oluşturmak için gerçek bir güç veriyor. Bu yüzden şimdi öğrenmeye başlamanızı tavsiye ederim. Bir çok açıdan REST’in yerini aldığı ve iyi bir puanla onu geçtiğini söyleyebilirim.

Zaman ayırıp okuduğunuz için teşekkür ederim. Arkadaşlarınızla paylaşmayı unutmayın. Keyifli Kodlamalar.

Sağlıcakla Kalın!

Paylaşmak İster Misiniz?