• I will use the Insomnia REST client for API calls instead of the 'graphiql' IDE -- if you don't already have it installed, go ahead and do that now!
  
  
• I will start with simple Order and Payment models, but eventually (in a future article) branch into more complicated relationships (and implementing features like filtering objects with custom methods directly on the model and has_many declaration)
  
  
• I will explore "idempotency" in GraphQL as part of Mutations (in a future article), using strategies covered in this EXCELLENT article by Todd Jefferson
  
  

Overview 

• create a Rails API
• add some models
• add GraphQL
• write and execute our first GraphQL Query

1. Query -- this allows us to get data ("Read" in CRUD)
2. Mutation -- this allows us to change information, including adding, updating, or removing data ("Create", "Update", "Destroy" in CRUD)

What is GraphQL? 

Creating the Rails app 

$ rails g model Order description:string total:float
$ rails g model Payment order_id:integer amount:float

# app/models/order.rb
class Order < ApplicationRecord
    has_many :payments
end

# app/models/payment.rb
class Payment < ApplicationRecord
    belongs_to :order
end

# db/seeds.rb
order1 = Order.create(description: "King of the Hill DVD", total: 100.00)
order2 = Order.create(description: "Mega Man 3 OST", total: 29.99)
order3 = Order.create(description: "Punch Out!! NES", total: 0.75)

payment1 = Payment.create(order_id: order1.id, amount: 20.00)
payment2 = Payment.create(order_id: order2.id, amount: 1.00)
payment3 = Payment.create(order_id: order3.id, amount: 0.25)

Adding GraphQL 

# Gemfile
gem 'graphql'

Filling out the new GraphQL files 

# app/graphql/types/payment_type.rb
module Types
    class PaymentType < Types::BaseObject
        field :id, ID, null: false
        field :amount, Float, null: false
    end
end

# app/graphql/types/order_type.rb
module Types
    class OrderType < Types::BaseObject
        field :id, ID, null: false
        field :description, String, null: false
        field :total, Float, null: false
        field :payments, [Types::PaymentType], null: false
        field :payments_count, Integer, null: false

        def payments_count
            object.payments.size
        end
    end
end

• Because the Order model has columns for id, description, and total, we can simply create a field for them and retrieve their data.
• Because of our has_many-belongs_to relationship, we can also make a payments field to return all Types::PaymentType objects belonging to each Order.
• However, Order does NOT have a payments_count column--so we define a payments_count() method to return an integer with the length of the payments array. 
  • NOTE: inside these custom field methods, we need to access the Order's payments through object.payments--don't forget that critical object!

# app/graphql/types/query_type.rb
module Types
    class QueryType < Types::BaseObject
        field :all_orders, [Types::OrderType], null: false

        def all_orders
            Order.all
        end
    end
end

Writing our first Query 

query {
    allOrders {
        id
        description
        total      
        payments {
            id
            amount
        }
        paymentsCount
    }
}

query {
    allOrders {
        description
        total      
        payments {
            amount
        }
    }
}

Conclusion 

Overview 

• create the needed Mutation files
• create our first mutation (add a new Order to the database)
• add routing to /app/graphql/types/mutation_type.rb
• write and execute our first GraphQL Mutation in Insomnia

What is a GraphQL Mutation? 

Most discussions of GraphQL focus on data fetching, but any complete data platform needs a way to modify server-side data as well.

mutation {
  createOrder(input: {
    description: "Octo Octa - Resonant Body (vinyl)",
    total: 21.82
  }) {
    order {
      id
      description
      total
      payments {
        id
        amount
      }
      paymentsCount
    }
    errors
  }
}

• At the very top, we define our request as a mutation instead of query--this is necessary for routing the request correctly, which we'll cover below
• createOrder is the name we will give to our mutation, and we call it like a function with the arguments inside parentheses: createOrder( input: {} )
• the mutation accepts input, structured as a hash, where we pass a string for description and a float for amount (we can set these inputs to optional, or make them required)
• following the closing parentheses from createOrder(), we add another hash to outline the data we want to return from the mutation 
  • notice that it looks essentially the same as our first query, except that we also return errors along with the new order we created
  • this return is optional, but it is a good idea--you can both mutate the database AND query the data in one atomic operation, which is very efficient!

Adding mutations to our /app/ 

1. Create a BaseMutation class for our mutations to inherit from
2. Create a specific mutation (createOrder) which inherits from BaseMutation
3. Add routing to /app/graphql/types/mutation_type.rb (much like we did with /app/graphql/types/query_type.rb in the previous article)

Creating a mutation 

# /app/graphql/mutations/base_mutation
class Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation
end

# /app/graphql/mutations/create_order.rb
class Mutations::CreateOrder < Mutations::BaseMutation
    argument :description, String, required: true
    argument :total, Float, required: true

    field :order, Types::OrderType, null: false
    field :errors, [String], null: false

    def resolve(description:, total:)
        order = Order.new(description: description, total: total, reference_key: SecureRandom.uuid)
        if order.save
            {
                order: order,
                errors: []
            }
        else
            {
                order: nil,
                errors: order.errors.full_messages
            }
        end
    end
end

# /app/graphql/mutations/create_order.rb
    argument :description, String, required: true
    argument :total, Float, required: true

1. name of the argument (:description)--we will use this as the key in our key-value pairs for inputs
2. data type (String)--the mutation request will throw errors if the correct data type is not provided
3. required, as a boolean (required: true)--this allows us to specify if an argument must be present to succeed 
   • required: true will throw an error if not present
   • required: false will make the argument optional

# /app/graphql/mutations/create_order.rb
    field :order, Types::OrderType, null: false
    field :errors, [String], null: false

• if the mutation is successful, an Order object will be returned (just like a Query)
• if the mutation fails, we will get back a set of errors

1. name of the field (:order, :errors)--we will use this as the key in our key-value pairs for our return data
2. data type (Types::OrderType, [String])--these tell us what type of data to expect in the return 
   • as with Queries, we can specify any data type, including our custom types created in the /app/graphql/types/ directory
   • we can also return an array of another type, such as returning an array of errors as strings via [String]
3. null, as a boolean (required: true)--this allows us to specify if we are allowed to receive nil fields in our return data 
   • null: false will throw an error a field is nil
   • null: true will allow nil data to be returned without errors

# /app/graphql/mutations/create_order.rb
    def resolve(description:, total:)
        order = Order.new(description: description, total: total)
        if order.save
            {
                order: order,
                errors: []
            }
        else
            {
                order: nil,
                errors: order.errors.full_messages
            }
        end
    end

• resolve() takes the arguments we specified above
• we immediately use ActiveRecord to create a new Order, using the data from the arguments
• in a familiar Rails pattern, we test if the Order can be saved in the database 
  • if successful, we return a hash with the order key containing our newly-saved Order instance, and an empty array of errors
  • if failed, we return a nil Order, and an array of errors

# /app/graphql/types/mutation_type.rb
module Types
  class MutationType < Types::BaseObject
  end
end

# /app/graphql/types/mutation_type.rb
module Types
  class MutationType < Types::BaseObject

    field :create_order, mutation: Mutations::CreateOrder

  end
end

Executing our first Mutation 

mutation {
  createOrder(input: {
    description: "Octo Octa - Resonant Body (vinyl)",
    total: 21.82
  }) {
    order {
      id
      description
      total
      payments {
        id
        amount
      }
      paymentsCount
    }
    errors
  }
}

• the top line says mutation {} instead of query {}--this is necessary for correct routing to /app/graphql/types/mutation_type.rb
• inside, we call createOrder() as a function, and supply input: as a hash containing our fields as keys
• immediately following the createOrder() call, we also provide a structure for the returned data, including an order and errors

mutation {
  createOrder(input: {
    total: 21.82
  }) {
    order {
      id
      description
      total
      payments {
        id
        amount
      }
      paymentsCount
    }
    errors
  }
}

Conclusion 

1. Custom Fields in our GraphQL Queries
2. Class Methods directly on our Rails Models (as inspired by this great StackOverflow response)

Overview 

• add a status column to our Payments table (and update our seed file)
• add a successful class method to our Order model to filter by "Successful" payments
• add a custom field to our GraphQL order_type to call the .successful class method
• write and execute a GraphQL query to demonstrate the filter in Insomnia

Use Case: Filtering by Status 

# /db/migrate/20190929153644_add_column_status_to_payments.rb

class AddColumnStatusToPayments < ActiveRecord::Migration[5.2]
  def change
    add_column :payments, :status, :string
  end
end

# /db/seeds.rb

Order.destroy_all
Payment.destroy_all

order1 = Order.create(description: "King of the Hill DVD", total: 100.00)
order2 = Order.create(description: "Mega Man 3 OST", total: 29.99)
order3 = Order.create(description: "Punch Out!! NES", total: 0.75)

payment1 = Payment.create(order_id: order1.id, amount: 20.00, status: "Successful")
payment2 = Payment.create(order_id: order2.id, amount: 1.00, status: "Successful")
payment3 = Payment.create(order_id: order3.id, amount: 0.25, status: "Successful")
payment4 = Payment.create(order_id: order1.id, amount: 5.00, status: "Failed")

# /app/models/order.rb

class Order < ApplicationRecord
    has_many :payments
end

[10:28:27] (master) devto-graphql-ruby-api
// ♥ rails c

Running via Spring preloader in process 6225
Loading development environment (Rails 5.2.3)

2.6.1 :001 > Order.all[0]
  Order Load (0.5ms)  SELECT "orders".* FROM "orders"
 => #<Order id: 16, description: "King of the Hill DVD", total: 100.0, created_at: "2019-09-29 17:20:34", updated_at: "2019-09-29 17:20:34"> 

2.6.1 :002 > Order.all[0].payments
  Order Load (0.2ms)  SELECT "orders".* FROM "orders"
  Payment Load (0.2ms)  SELECT  "payments".* FROM "payments" WHERE "payments"."order_id" = ? LIMIT ?  [["order_id", 16], ["LIMIT", 11]]
 => #<ActiveRecord::Associations::CollectionProxy [#<Payment id: 1, order_id: 16, amount: 20.0, created_at: "2019-09-29 17:20:34", updated_at: "2019-09-29 17:20:34", status: "Successful">, #<Payment id: 4, order_id: 16, amount: 5.0, created_at: "2019-09-29 17:20:34", updated_at: "2019-09-29 17:20:34", status: "Failed">]> 

Class Methods on Rails Models 

# /app/models/order.rb

class Order < ApplicationRecord
    has_many :payments do
        # we can add additional functionality here!
    end
end

# /app/models/order.rb

class Order < ApplicationRecord
    has_many :payments do
        def successful
            where("status = ?", "Successful")
        end
    end
end

[10:41:36] (master) devto-graphql-ruby-api
// ♥ rails c

Running via Spring preloader in process 6277
Loading development environment (Rails 5.2.3)

2.6.1 :001 > Order.all[0].payments
  Order Load (1.0ms)  SELECT "orders".* FROM "orders"
  Payment Load (0.2ms)  SELECT  "payments".* FROM "payments" WHERE "payments"."order_id" = ? LIMIT ?  [["order_id", 16], ["LIMIT", 11]]
 => #<ActiveRecord::Associations::CollectionProxy [#<Payment id: 1, order_id: 16, amount: 20.0, created_at: "2019-09-29 17:20:34", updated_at: "2019-09-29 17:20:34", status: "Successful">, #<Payment id: 4, order_id: 16, amount: 5.0, created_at: "2019-09-29 17:20:34", updated_at: "2019-09-29 17:20:34", status: "Failed">]> 

2.6.1 :002 > Order.all[0].payments.successful
  Order Load (0.2ms)  SELECT "orders".* FROM "orders"
  Payment Load (0.4ms)  SELECT  "payments".* FROM "payments" WHERE "payments"."order_id" = ? AND (status = 'Successful') LIMIT ?  [["order_id", 16], ["LIMIT", 11]]
 => #<ActiveRecord::AssociationRelation [#<Payment id: 1, order_id: 16, amount: 20.0, created_at: "2019-09-29 17:20:34", updated_at: "2019-09-29 17:20:34", status: "Successful">]> 

Add a Custom Field to a Query 

# /app/graphql/types/payment_type.rb

module Types
  class PaymentType < Types::BaseObject
    field :id, ID, null: false
    field :amount, Float, null: false
  end
end

# /app/graphql/types/payment_type.rb

module Types
  class PaymentType < Types::BaseObject
    field :id, ID, null: false
    field :amount, Float, null: false
    field :status, String, null: false
  end
end

query {
    allOrders {
        id
        description
        total      
        payments {
            id
            amount
            status
        }
        paymentsCount
    }
}

# /app/graphql/types/order_type.rb

module Types
  class OrderType < Types::BaseObject
    field :id, ID, null: false
        field :description, String, null: false
        field :total, Float, null: false
        field :payments, [Types::PaymentType], null: false
        field :payments_count, Integer, null: false

        def payments_count
            object.payments.size
        end
  end
end

# /app/graphql/types/order_type.rb

module Types
  class OrderType < Types::BaseObject
    field :id, ID, null: false
        field :description, String, null: false
        field :total, Float, null: false
        field :payments, [Types::PaymentType], null: false
        field :payments_count, Integer, null: false
        field :successful_payments, [Types::PaymentType], null: false

        def payments_count
            object.payments.size
        end

        def successful_payments
            object.payments.successful
        end
  end
end

query {
    allOrders {
        id
        description
        total      
        successfulPayments {
            id
            amount
            status
        }
    }
}

Conclusion