GraphQL Şema / Schema Nedir?

GraphQL şeması (schema) bir GraphQL API’sinde istenilen verilerin açıklamasıdır. Ayrıca veri ekleme, düzenleme ve silme gibi işlemler için gerekli tanımlamaları yapar.

API üzerinde kullanılacak veri türlerini tanımlandığı yer olan şema, ayrıca veriler üzerinde işlem yapmak için gerekli olan metodları (mutation) ve API üzerinden bilgileri almak için gerekli sorguların (query) tanımlandığı bir şemadır.

Farklı programlama dillerinde ve farklı paketlerde tanımlanması için gerekli işlemler bir birinden farklı olabilir.

GraphQL Veri Tanımlama / Type

Şimdi genel kullanımını bir yazar ve kitap verilerini tanımlayarak görelim.

const typeDefs = `#graphql
    type Yazar {
        id: ID!
        isim: String!
        eposta: String!
        sehir: String
        yas: Int
        kitaplar: [Kitap!]
    }

    type Kitap {
        id: ID!
        baslik: String!
        sayfaSayisi: Int
        yayinlandi: Boolean
        yazarID: ID!
    }
`

Örnekte görüldüğü gibi şema içerisinde Yazar ve Kitap veri türlerini (nesnelerini) tanımlamış olduk. Artık API üzerinde bu verileri kullanabiliriz demektir. Fakat aslında tam olarak şemanın işleme alınması için resolvers adı altında şema içeriğinin uygulamadaki karşılığı oluşturulmalıdır.

GraphQL Sorgu Oluşturma / Query

Veri tanımlarından başka şema içerisinde sorguları da Query altında tanımlayabiliriz. Şimdide sorguları şemamıza ekleyelim.

const typeDefs = `#graphql
    type Yazar {
        id: ID!
        isim: String!
        eposta: String!
        sehir: String
        yas: Int
        kitaplar: [Kitap!]
    }

    type Kitap {
        id: ID!
        baslik: String!
        sayfaSayisi: Int
        yayinlandi: Boolean
        yazarID: ID!
    }

    type Query {
        yazar(id: ID!): Yazar!
        yazarlar: [Yazar]
        kitap(id: ID!): Kitap!
        kitaplar: [Kitap]
    }
`

Örneğimizde dört adet sorgu oluşturduk. Bunlardan yazar sorgusu bir ID değeri alır ve sonucunda eğer bu ID değeri bir yazarın ID’sine eşitse o yazarın bilgilerini geri dönderir.

Yine yazarlar sorgusu ise tüm yazarları bir dizi içerisinde geri dönderir. Kitap verisi için de benzer iki adet sorgu oluşturduk.

GraphQL CRUD İşlemleri İçin Metod Oluşturma / Mutation

Yine mesela kitap eklememiz, kitap bilgilerini güncellememiz veya bir kitabı silmemiz gerekebilir. Bu tip durumlar için yaptığımız tanımlamalara mutation diyoruz. Mutation tanımlamalarını da şema içerisinde yapıyoruz.

Şimdi Kitap veri türü için, kitapEkle, kitapDuzenle ve kitapSil şeklinde üç adet mutation (metod) yazalım.

const typeDefs = `#graphql
    type Yazar {
        id: ID!
        isim: String!
        eposta: String!
        sehir: String
        yas: Int
        kitaplar: [Kitap!]
    }

    type Kitap {
        id: ID!
        baslik: String!
        sayfaSayisi: Int
        yayinlandi: Boolean
        yazarID: ID!
    }

    type Query {
        yazar(id: ID!): Yazar!
        yazarlar: [Yazar]
        kitap(id: ID!): Kitap!
        kitaplar: [Kitap]
    }

    type Mutation {
        kitapEkle(baslik: String!, sayfaSayisi: Int!, yayinlandi: Boolean, yazarID: ID): Kitap!
        kitapDuzenle(baslik: String, sayfaSayisi: Int, yayinlandi: Boolean, yazarID: ID): Kitap!
        kitapSil(id: ID!): Kitap!
    }
`

Bir mutation tanımlarken, verilecek bilgileri onların türleri ile belirtiyoruz. Sonra geri dönüş türünü de iki nokta (:) işaretinden sonra bilirtiyoruz.

Yine belirli bir işlem sonucunda yapılacak işlemler varsa subscribe tanımlamaları da yapılabilir.

Yukarıda belirttiğimiz gibi şema içerisinde sadece tanımlamalar yapılır. Bu tanımlamaların çalışması için ayrıca resolvers adı altında yapılacak işlemlerin ayrıca kodlanması gerekmektedir.

GraphQL Şema Üzerine Yorum Satırı Ekleme

Eğer bir şemanın üzerine yorum satırı eklenecekse, yapılması gereken yorum yazılacak satırın başına kare (#) işaretini eklemektir. GraphQL başında # işareti olan satırları yorum satırı olarak kalbul eder ve işleme almaz.

const typeDefs = `#graphql
    # Yazar tanımı başlıyor
    type Yazar {
        ...
    }    # Bu farklı bir yorum satırıdır

`

Sonuç

GraphQL ile bir API oluşturulurken kullanılacak veriler, veriler üzerinde yapılacak sorgular, veriler için kullanılacak metodlar ve ayrıca bir işlem sonucunda yapılacak işlemler için tanımlamaların tamamı şema (schema) üzerinde tanımlanır.

Sorularınızı ve eklemek istediklerinizi yorumlara ekleyebilirsiniz.