Bu yazıya başlamadan öncelikle GraphQL nedir, neden ortaya çıktı, nasıl bir yaklaşıma sahip gibi soruların cevaplarını merak ediyorsanız ilk yazımızı okumanızda fayda var.
API’ler yazılımcılar olarak sıkça yazdığımız yada iletişime geçtiğimiz sistemler. API geliştirmek için SOAP veya REST mimarisini kullanıyoruz. Şimdi ise yeni bir yöntem olarak GraphQL mevcut.
SOAP —> Rest —> GraphQL
GraphQL’i kullanabileceğiniz bir çok dil mevcut.
Peki neden SOAP veya Rest değil?
Şöyle düşünebiliriz; bir web veya mobil uygulamanız var ki servis mimarisini kullanıyorsak muhtemelen birden fazla client mevcut. Web, Android, iOS hatta akıllı saat veya tv için uygulamalarımız mevcut. Bu uygulamaların temel ihtiyaçları ortak olsa da bazı noktalarda farklı verilere veya bir datanın farklı özelliklerine ihtiyacı olabilir. Mobil’de kullanıcıların bazı detaylarına yer verilmezken web tarafında bütün detayları gösterebiliriz. Geliştirdiğimiz servisin response şöyle olabilir.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 |
{ "users":[ { "id":1, "name":"cem", "surname":"dırman", "detail":{ "created_at":"2019-03-22 23:33:52", "age":"25" "country":"tr" }, "posts":[] }, { "id":2, "name":"Ahmet", "surname":"ak", "detail":{ "created_at":"2019-03-22 23:33:52", "age":"22" "country":"tr" } "posts":[] }, { "id":3, "name":"Ayşe", "surname":"Sarı", "detail":{ "created_at":"2019-03-22 23:33:52", "age":"20" "country":"tr" } "posts":[] } ] } |
GET users/ bütün user’ların döndüğü end-point
GET users/2 id’si 2 olan user’ın döndüğü end-point.
Uygulamanızın farklı yerlerinde aynı servisten gelen farklı datalarını kullanıyor olabiliriz. Örneğin bir ekranda bütün postları dönen servisimizin sadece post adlarını kullanıyorsunuz başka bir sayfada veya component ise postların diğer detaylarını da kullanıcıya gösteriyorsunuz. Buradaki sorun şöyle, aynı servisi çağırıp bütün dataları fetch ediyoruz fakat o datanın çok ufak bir parçasını kullanıyoruz. Peki neden kullanmadığımız dataları dönüyor bu servis? Peki neden kullanmadığımız dataları getiriyoruz? Bu sorunu aşmak için ise yeni bir servis metodu yazabiliriz ve sorunu çözmüş oluruz. Fakat bu işlem bir maliyet doğurur.
GraphQL bu noktada farklı bir yaklaşım sergiliyor. Tek bir end-point üzerinden sadece ihtiyacınız olan dataları fetch edebilirsiniz. Tabi burada tek end-point olması tek bir servis metodu olduğu anlamına gelmiyor. Ulaştığınız end-point tek iken birden fazla metoda ulaşıp, istediğiniz servisin istediğiniz datalarını alabilirsiniz. Sadece ihtiyacımız olan data kısmını vurguladık çünkü Rest yada SOAP mimarisinde sorguladığımız servis hangi dataları bize sunuyorsa o dataları kullanıyoruz. Fakat GraphQL’de sorguladığınız servis ile hangi dataları almak istediğinizi belirtmeniz yeterli.
Nasıl?
Resimde de görülen üç aşama GraphQL mimarisini ortaya koymaktadır.
1) Describe your data: sorgulamak istediğiniz veri kümesini tanımlıyorsunuz. Bu tanımlama işlemi servisten dönmesini istediğiniz veri kümesini belirtir.
Schema ve Type
Schema, tanımlamaları yaptığımız dosyamız. Bu işlemi kod tarafında da yapabilirsiniz. Schema farklı türde verileri içerebilir.
GraphQL bazı data tiplerini desteklemektedir;
- String
- Int
- Float
- Boolean
- ID
- Custom Type
|
1 2 3 4 5 |
type Author {id: Int!firstName: StringlastName: Stringposts: [Post]}type Post {id: Int!title: Stringauthor: Authorvotes: Int} |
Bizim örneğimizde Post ve Author Custom Type olarak yer almakta. Siz de kendi schema tanımlarınızda kendi type’larınızı oluşturup kullanabilirsiniz. Yukarıda belirtilen type’ların haricinde belki en çok ihtiyaç duyulan Date bulunmamakta. Bunları scalar key-word ile kendiniz ayrıca tanımlanız gerekecek.
|
1 2 3 4 5 |
scalar Date |
Çok kullandığımız bir diğer yapı olan enum’ları da bu schema içerisinde tanımlayıp kullanabilirsiniz.
|
1 2 3 4 5 |
enum USER_STATE{ NOT_FOUND ACTIVE INACTIVE } |
Bir değerin liste olduğunu belirtmek için ise köşeli parantezleri kullanıyoruz.
|
1 2 3 4 5 |
posts: [Post]type Query {posts: [Post]author(id: Int!): Author} |
İşlemler(Operation)
GraphQL kendisini Query Language olarak tanımlıyor. Yani temelde yaptığımız işlem servis metodlarını kendine has query ile sorgulamak. Json yapısına benzese de değildir. Key / Value ilişkisine benzetebileceğimiz bir yapısı mevcut kaldı ki key / value ilişkisini kullanan mantık bir çok yerde karşımıza çıkmakta.
Yukarıda Rest mimarisiyle yazıldığını farzettiğimiz json response bir de GraphQL ile örnekleyelim.
Sadece user’ların name ve surname alanlarını sorguluyoruz. Query’e almak istediğimiz diğer alanları da ekleyebiliriz. Kullanılan query GraphQL’in kendine özgü bir sorgulama şekli.
|
1 2 3 4 5 6 7 8 9 10 |
{ users{ name surname } } |
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
{ "users":[ { "name":"cem", "surname":"dırman", }, { "name":"Ahmet", "surname":"ak", }, { "name":"Ayşe", "surname":"Sarı", } ] } |
Sadece id’si ‘ olan user’ın name ve surname alanlarını sorguluyoruz.
|
1 2 3 4 5 6 7 |
{ users(id:2){ name surname email } } //--- Response |
Schema tanımlarında type tanımlarını yaptıktan sonra GraphQL’in sahip olacağı metodları da tanımlamamız gerek. Temel olarak GraphQL’de 3 işlemi gerçekleştirebilirsiniz.
- Query: sadece okuma işlemini yapabileceğiniz işlem türü.
- Mutation: Create, update ve delete işlemleri için
2) Ask for what you want: tanımlanan veri kümesi içerisinden hangi veri veya veri grubunu sorgulamak istediğinizi belirtiyorsunuz. Bu aşama client tarafında gerçekleştirilen bir işlem.
3) Get predictable results: ikinci aşamada hangi bilgileri istediysek ona göre response alırız.
Görseldeki resim starwars temalı bir GrahpQL servisten alınmıştır. Sizde bu servisi kullanarak GrahpQL’i deneyimleyebilirsiniz.
Dökümantasyon
Yazdığımız servisin dökümante edilmesi en büyük problemlerden biridir. Hangi fonksiyonların olduğu, hangi parametrelerle sorgulanabilir ve dönüş değeri olarak bize ne verdiği soruları servisi kullanlar tarafından önemlidir. Dökümantasyon için Apollo tarafından GraphiQL adında bir tool geliştirilmiştir. Bu tool sizin ekstra hiç şey yapmanıza gerek kalmadan servisinizi dökümantasyonunu kendiliğinden gerçekleştiriyor.
Kaynak: