GraphQL Introduction

What is GraphQL?

GraphQL is a query language for APIs that allows clients to request exactly the data they need.

GraphQL vs REST

GraphQL Endpoint

# Magento GraphQL endpoint
POST https://store.com/graphql

# With store code
POST https://store.com/{store_code}/graphql

Query Example

query {
    products(filter: { sku: { eq: "SKU-123" } }) {
        items {
            name
            sku
            price {
                regularPrice {
                    amount {
                        value
                    }
                }
            }
        }
    }
}

Response

{
    "data": {
        "products": {
            "items": [
                {
                    "name": "Test Product",
                    "sku": "SKU-123",
                    "price": {
                        "regularPrice": {
                            "amount": {
                                "value": 29.99
                            }
                        }
                    }
                }
            ]
        }
    }
}

GraphQL Schema

type Product {
    id: ID!
    name: String!
    sku: String!
    price: ProductPrice
    description: String
    image: ProductImage
}

type ProductPrice {
    regularPrice: Price
    finalPrice: Price
}

type Price {
    amount: Money
}

type Money {
    value: Float!
    currency: String!
}

# Query type
type Query {
    products(filter: ProductFilterInput): ProductSearchResult
    product(sku: String!): Product
}

# Input types
input ProductFilterInput {
    sku: FilterEqualTypeInput
    name: FilterMatchTypeInput
}

input FilterEqualTypeInput {
    eq: String
    in: [String]
}

Scalar Types

Object Types

type Customer {
    id: ID!
    email: String!
    firstname: String!
    lastname: String!
    addresses: [CustomerAddress]
}

type CustomerAddress {
    id: ID!
    street: [String]!
    city: String!
    region: Region!
    postcode: String!
    country: Country!
}

Basic Query

query {
    products {
        items {
            name
            sku
            price {
                regularPrice {
                    amount {
                        value
                    }
                }
            }
        }
    }
}

Query with Arguments

query {
    product(sku: "SKU-123") {
        name
        sku
        description
        price {
            regularPrice {
                amount {
                    value
                    currency
                }
            }
        }
    }
}

Query with Filters

query {
    products(
        filter: {
            name: { match: "shirt" }
            price: { from: "10" to: "50" }
        }
        sort: { price: ASC }
        pageSize: 10
        currentPage: 1
    ) {
        total_count
        items {
            name
            sku
            price {
                regularPrice {
                    amount {
                        value
                    }
                }
            }
        }
        page_info {
            page_size
            current_page
        }
    }
}

Named Query

query GetProductBySku($sku: String!) {
    product(sku: $sku) {
        name
        sku
        price {
            regularPrice {
                amount {
                    value
                }
            }
        }
    }
}

# Variables
{
    "sku": "SKU-123"
}

Mutation Example

mutation {
    addSimpleProductsToCart(
        input: {
            cartId: "cart123",
            cartItems: [
                {
                    data: {
                        quantity: 1
                        sku: "SKU-123"
                    }
                }
            ]
        }
    ) {
        cart {
            items {
                product {
                    name
                    sku
                }
                quantity
            }
        }
    }
}

Resolver Structure

<?php
namespace Vendor\Module\GraphQl\Resolver;

use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;
use Magento\Framework\GraphQl\Resolver\ResolverInterface;

class ProductResolver implements ResolverInterface
{
    public function resolve(
        Field $field,
        $context,
        ResolveInfo $info,
        array $value = null,
        array $args = null
    ) {
        $productId = $value['product_id'];
        
        $product = $this->productRepository->getById($productId);
        
        return [
            'name' => $product->getName(),
            'sku' => $product->getSku(),
            'price' => $product->getPrice()
        ];
    }
}

Resolver Configuration

<!-- etc/schema.graphqls -->
<config>
    <type name="Query">
        <field name="product" resolver="Vendor\Module\GraphQl\Resolver\ProductResolver"/>
    </type>
</config>

Resolver for Custom Type

public function resolve(
    Field $field,
    $context,
    ResolveInfo $info,
    array $value = null,
    array $args = null
) {
    return [
        'id' => $value['id'],
        'name' => $value['name'],
        'email' => $value['email'],
        'created_at' => $value['created_at']
    ];
}