Ruby on Rails ile GraphQL API Kurulumu: Kapsamlı Bir Rehber

Ruby on Rails ile GraphQL API Kurulumu: Kapsamlı Bir Rehber

Modern web uygulamaları, veriye erişim ve veri yönetimi konusunda esneklik ve verimlilik arayışındadır. Geleneksel REST mimarisi birçok senaryoda yeterli olsa da, özellikle karmaşık ve hızla değişen frontend ihtiyaçları karşısında GraphQL, önemli avantajlar sunar. Bu rehberde, Ruby on Rails çerçevesini kullanarak güçlü ve esnek bir GraphQL API’sinin nasıl kurulacağını adım adım inceleyeceğiz.

GraphQL Nedir ve Neden Rails ile Kullanılmalı?

GraphQL, Facebook tarafından geliştirilmiş, API’ler için bir sorgu dili ve çalışma zamanıdır. En temel özelliği, istemcinin tam olarak hangi veriye ihtiyaç duyduğunu belirlemesine olanak tanımasıdır. Bu, aşırı veri getirme (over-fetching) veya yetersiz veri getirme (under-fetching) sorunlarını ortadan kaldırır. Tek bir endpoint üzerinden birden fazla kaynak sorgulanabilir ve yanıt, istemcinin istediği formatta gelir.

Ruby on Rails, hızlı geliştirme, güçlü bir ekosistem ve “convention over configuration” felsefesiyle bilinir. graphql-ruby gem’i sayesinde, Rails uygulamalarınıza GraphQL desteğini entegre etmek oldukça kolaydır. Rails’in model-view-controller (MVC) yapısı, GraphQL şemanızı ve resolver’larınızı düzenli bir şekilde organize etmenize olanak tanır, bu da büyük projelerde bile yönetilebilirliği artırır.

Rails Projesini Hazırlama ve GraphQL Gem’ini Entegre Etme

İlk adım olarak, yeni bir Rails projesi oluşturalım veya mevcut bir projenize GraphQL’i ekleyelim. Bu rehber için yeni bir proje ile başlayacağız.

rails new graphql_api_example --api
cd graphql_api_example

--api bayrağı, projemizi bir API olarak yapılandırır, bu da gereksiz view dosyalarını ve frontend bağımlılıklarını devre dışı bırakır. Şimdi, graphql-ruby gem’ini projemize ekleyelim. Gemfile dosyanızı açın ve aşağıdaki satırı ekleyin:

# Gemfile
gem 'graphql'

Değişiklikleri kaydettikten sonra, gem’i yüklemek için bundle install komutunu çalıştırın:

bundle install

Şimdi, graphql-ruby gem’inin kurulum komutunu çalıştırarak temel GraphQL yapılandırmasını oluşturalım:

rails generate graphql:install

Bu komut, projenizde birkaç önemli dosya oluşturacaktır:

• app/graphql/graphql_api_example_schema.rb: Ana GraphQL şemanız.
• app/graphql/types/base_object.rb, app/graphql/types/base_argument.rb, vb.: GraphQL tipleri için temel sınıflar.
• app/graphql/types/query_type.rb: Ana sorgu tipiniz.
• app/controllers/graphql_controller.rb: GraphQL isteklerini işleyecek kontrolcü.
• config/routes.rb: GraphQL endpoint’i için rota.

Bu adımlarla, Rails projemiz GraphQL isteklerini almaya hazır hale geldi.

GraphQL Şemasını ve Tipleri Tanımlama

GraphQL’in kalbi, verinin nasıl sorgulanabileceğini ve değiştirilebileceğini tanımlayan şemadır. Şemayı tanımlamak için öncelikle veri modellerimize ihtiyacımız var. Basit bir Post modeli oluşturalım:

rails generate model Post title:string content:text
rails db:migrate

PostType Oluşturma

Şimdi, Post modelini GraphQL üzerinden erişilebilir kılmak için bir PostType tanımlayalım. app/graphql/types dizininde yeni bir dosya oluşturun: post_type.rb.

# app/graphql/types/post_type.rb
module Types
  class PostType < Types::BaseObject
    field :id, ID, null: false
    field :title, String, null: false
    field :content, String, null: true
    field :created_at, GraphQL::Types::ISO8601DateTime, null: false
    field :updated_at, GraphQL::Types::ISO8601DateTime, null: false
  end
end

Burada, PostType sınıfı Types::BaseObject'tan miras alır ve Post modelinin hangi alanlarının GraphQL üzerinden erişilebilir olacağını tanımlarız. field metodu ile alanın adını, tipini (ID, String, GraphQL::Types::ISO8601DateTime gibi) ve null olup olamayacağını belirtiriz.

QueryType'a Alan Ekleme

Kullanıcıların postları sorgulayabilmesi için QueryType'a bir alan eklememiz gerekiyor. app/graphql/types/query_type.rb dosyasını açın ve aşağıdaki gibi düzenleyin:

# app/graphql/types/query_type.rb
module Types
  class QueryType < Types::BaseObject
    # Add root-level fields here.
    # They will be entry points for queries on your schema.

    field :posts, [Types::PostType], null: false, description: "Tüm blog gönderilerini listeler"
    def posts
      Post.all
    end

    field :post, Types::PostType, null: true, description: "Belirli bir blog gönderisini getirir" do
      argument :id, ID, required: true
    end
    def post(id:)
      Post.find_by(id: id)
    end
  end
end

Yukarıdaki kodda, iki yeni alan ekledik: posts ve post.

• posts: Tüm PostType nesnelerinin bir dizisini döndürür. def posts metodu, bu sorgu çağrıldığında çalışacak olan resolver'dır.
• post: Tek bir PostType nesnesi döndürür ve bir id argümanı alır. def post(id:) metodu, bu argümanı kullanarak ilgili postu bulur.

Bu yapılandırma ile artık postları sorgulayabiliriz.

Mutasyonları Ekleme: Veri Oluşturma ve Güncelleme

GraphQL'de veri oluşturma, güncelleme ve silme işlemleri "Mutasyonlar" aracılığıyla yapılır. Mutasyonlar, sorgulardan farklı olarak sunucu tarafında veri değişikliklerine neden olur. Bir mutasyon tanımlamak için öncelikle MutationType'ı oluşturmamız ve ardından özel mutasyon sınıflarını eklememiz gerekir.

MutationType Oluşturma

graphql:install komutu, varsayılan olarak bir mutation_type.rb dosyası oluşturmaz. Bizim oluşturmamız gerekiyor. app/graphql/types dizininde mutation_type.rb adında bir dosya oluşturun:

# app/graphql/types/mutation_type.rb
module Types
  class MutationType < Types::BaseObject
    # TODO: remove me
    field :test_field, String, null: false,
      description: "An example field added by the generator"
    def test_field
      "Hello World"
    end
  end
end

Bu dosya oluşturulduktan sonra, ana şemamızı (graphql_api_example_schema.rb) bu mutasyon tipini kullanacak şekilde güncellememiz gerekir:

# app/graphql/graphql_api_example_schema.rb
class GraphqlApiExampleSchema < GraphQL::Schema
  mutation(Types::MutationType) # Bu satırı ekleyin veya yorumu kaldırın
  query(Types::QueryType)

  # ... diğer ayarlar ...
end

CreatePost Mutasyonu Oluşturma

Şimdi, yeni bir post oluşturmak için bir mutasyon tanımlayalım. app/graphql/mutations dizini altında (bu dizini elle oluşturmanız gerekebilir) create_post.rb adında bir dosya oluşturun:

# app/graphql/mutations/create_post.rb
module Mutations
  class CreatePost < BaseMutation
    argument :title, String, required: true
    argument :content, String, required: false

    field :post, Types::PostType, null: true
    field :errors, [String], null: false

    def resolve(title:, content: nil)
      post = Post.new(title: title, content: content)
      if post.save
        { post: post, errors: [] }
      else
        { post: nil, errors: post.errors.full_messages }
      end
    end
  end
end

Yukarıdaki mutasyon sınıfında:

• argument: Mutasyonun alacağı giriş argümanlarını tanımlarız (title ve content).
• field: Mutasyonun döndüreceği çıktı alanlarını tanımlarız (oluşturulan post nesnesi ve olası errors).
• resolve: Mutasyonun asıl iş mantığını içeren metoddur. Burada, yeni bir Post nesnesi oluşturulur ve kaydedilir. Başarılı olursa postu ve boş bir hata dizisini, başarısız olursa nil postu ve hata mesajlarını döndürürüz.

MutationType'a Mutasyonu Ekleme

Oluşturduğumuz CreatePost mutasyonunu MutationType'a eklememiz gerekiyor. app/graphql/types/mutation_type.rb dosyasını açın ve aşağıdaki gibi güncelleyin:

# app/graphql/types/mutation_type.rb
module Types
  class MutationType < Types::BaseObject
    field :create_post, mutation: Mutations::CreatePost
    # field :update_post, mutation: Mutations::UpdatePost (benzer şekilde ekleyebilirsiniz)
    # field :delete_post, mutation: Mutations::DeletePost (benzer şekilde ekleyebilirsiniz)
  end
end

Artık API'miz üzerinden yeni postlar oluşturabiliriz.

GraphQL Endpoint'ini Yapılandırma ve Test Etme

graphql:install komutu, app/controllers/graphql_controller.rb dosyasını ve config/routes.rb dosyasında bir rota oluşturmuştu. Genellikle bu yapılandırma yeterlidir.

# config/routes.rb
Rails.application.routes.draw do
  post "/graphql", to: "graphql#execute"
  # Eğer geliştirme ortamında GraphiQL kullanmak isterseniz:
  if Rails.env.development?
    mount GraphiQL::Rails::Engine, at: "/graphiql", graphql_path: "/graphql"
  end
end

GraphiQL::Rails::Engine, tarayıcı tabanlı bir GraphQL IDE'sidir ve API'nizi test etmek için harika bir araçtır. Geliştirme ortamında /graphiql adresine giderek kullanabilirsiniz. GraphiQL'i kullanabilmek için Gemfile'a eklemeniz gerekebilir:

# Gemfile
group :development do
  gem 'graphiql-rails'
end

bundle install

Şimdi sunucuyu başlatın:

rails s

Tarayıcınızda http://localhost:3000/graphiql adresine giderek API'nizi test edebilirsiniz.

Örnek Sorgular ve Mutasyonlar

Tüm Postları Sorgulama

query {
  posts {
    id
    title
    content
    createdAt
  }
}

Belirli Bir Postu Sorgulama

query {
  post(id: "1") {
    id
    title
    content
  }
}

Yeni Bir Post Oluşturma Mutasyonu

mutation {
  createPost(input: {
    title: "İlk GraphQL Postu",
    content: "Bu benim Rails ile oluşturduğum ilk GraphQL postu içeriği."
  }) {
    post {
      id
      title
      content
    }
    errors
  }
}

Bu örneklerle, GraphQL API'nizin temel sorgu ve mutasyon yeteneklerini test edebilirsiniz.

Sonuç ve Sıkça Sorulan Sorular

Bu rehberde, Ruby on Rails kullanarak temel bir GraphQL API'sinin nasıl kurulacağını, şemanın, tiplerin ve mutasyonların nasıl tanımlanacağını ve API'nin nasıl test edileceğini öğrendik. GraphQL, modern uygulamalar için esnek ve güçlü bir veri katmanı sunar. Rails ile entegrasyonu sayesinde, hızlı ve verimli bir şekilde API'ler geliştirebilirsiniz.

Daha ileri adımlar olarak, kimlik doğrulama (authentication) ve yetkilendirme (authorization), N+1 sorgu sorununu çözmek için dataloader kullanımı, gerçek zamanlı güncellemeler için subscriptions ve daha karmaşık veri ilişkilerini yönetmek için ileri düzey tipler ve resolver'lar konularını araştırabilirsiniz.

Sıkça Sorulan Sorular (SSS)

GraphQL, REST'ten daha mı iyi?

Daha iyi veya kötü demek yerine, farklı ihtiyaçlara yönelik olduklarını söylemek daha doğru olur. GraphQL, özellikle mobil uygulamalar ve tek sayfa uygulamalar (SPA) gibi istemcinin veri ihtiyaçlarının sık değiştiği ve çok sayıda farklı kaynaktan veri çekmenin gerektiği durumlarda daha esneklik ve verimlilik sunar. REST, daha basit API'ler ve kaynak odaklı mimariler için hala harika bir seçenektir.

GraphQL API'mde kimlik doğrulama ve yetkilendirmeyi nasıl yaparım?

Rails'teki mevcut kimlik doğrulama (örneğin Devise) ve yetkilendirme (örneğin Pundit, CanCanCan) çözümlerini GraphQL ile entegre edebilirsiniz. Genellikle, context objesini kullanarak mevcut kullanıcı bilgilerini resolver'lara aktarır ve resolver'lar içinde yetki kontrollerini yaparsınız. Örneğin, GraphQLController içinde current_user'ı context'e ekleyebilirsiniz.

N+1 sorgu sorununu GraphQL'de nasıl çözerim?

N+1 sorgu sorunu, bir ana sorgu sonucunda dönen her nesne için ilişkili verileri çekmek amacıyla ek sorguların çalıştırılmasıyla ortaya çıkar. graphql-ruby gem'i, bu sorunu çözmek için GraphQL::Dataloader'ı destekler. Dataloader, ilgili verileri toplu halde (batch) tek bir sorgu ile çekerek performansı artırır.

GraphQL Subscriptions nedir ve Rails ile nasıl kullanılır?

Subscriptions, GraphQL'in gerçek zamanlı özellikler sunmasını sağlayan bir mekanizmadır. İstemciler, belirli bir olaya abone olabilir ve bu olay gerçekleştiğinde sunucudan otomatik olarak veri güncellemeleri alabilirler. Rails tarafında, Action Cable gibi WebSocket çözümleriyle entegre edilerek gerçek zamanlı uygulamalar oluşturulabilir. graphql-ruby gem'i, subscriptions için yerleşik destek sunar.