GraphQL in Magento 2 – custom resolver, schema, authorization, testing in DDEV

Magento 2.3 introduced GraphQL as an alternative to the REST API. Where REST requires separate endpoints for each resource, GraphQL lets the client decide what data it needs in a single query. I show how to write a custom resolver and expose data through GraphQL in a Magento 2 module.

GraphQL vs REST in the context of Magento 2

The Magento REST API returns a predetermined structure. When the frontend only needs product name and price, it still receives dozens of fields. GraphQL lets you ask for exactly what you need:

# GraphQL query - the client decides what it receives
query {
    products(search: "shoes", pageSize: 5) {
        items {
            name
            sku
            price_range {
                minimum_price {
                    final_price { value currency }
                }
            }
        }
    }
}

Module structure

Vendor/Module/
  etc/
    module.xml
    schema.graphqls
  Model/
    Resolver/
      Subscription.php
      Subscriptions.php
  registration.php

Schema definition – schema.graphqls

type Query {
    newsletterSubscription(email: String!): SubscriptionOutput
        @resolver(class: "Vendor\\Module\\Model\\Resolver\\Subscription")

    newsletterSubscriptions(pageSize: Int = 20, currentPage: Int = 1): SubscriptionsOutput
        @resolver(class: "Vendor\\Module\\Model\\Resolver\\Subscriptions")
}

type SubscriptionOutput {
    id: Int
    email: String
    status: String
    created_at: String
}

type SubscriptionsOutput {
    items: [SubscriptionOutput]
    total_count: Int
    page_info: SearchResultPageInfo
}

type Mutation {
    subscribeNewsletter(input: SubscribeInput!): SubscriptionOutput
        @resolver(class: "Vendor\\Module\\Model\\Resolver\\Subscribe")
}

Resolver – PHP implementation

<?php

namespace Vendor\Module\Model\Resolver;

use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Query\ResolverInterface;
use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;
use Vendor\Module\Api\SubscriptionRepositoryInterface;

class Subscription implements ResolverInterface
{
    public function __construct(
        private SubscriptionRepositoryInterface $subscriptionRepository
    ) {}

    public function resolve(
        Field $field,
        mixed $context,
        ResolveInfo $info,
        ?array $value = null,
        ?array $args = null
    ): array {
        $email = $args['email'] ?? null;

        if (!$email) {
            throw new \Magento\Framework\GraphQl\Exception\GraphQlInputException(
                __('Email is required')
            );
        }

        try {
            $subscription = $this->subscriptionRepository->getByEmail($email);
        } catch (\Magento\Framework\Exception\NoSuchEntityException $e) {
            throw new \Magento\Framework\GraphQl\Exception\GraphQlNoSuchEntityException(
                __('Subscription not found for email: %1', $email)
            );
        }

        return [
            'id'         => $subscription->getId(),
            'email'      => $subscription->getEmail(),
            'status'     => $subscription->getStatus(),
            'created_at' => $subscription->getCreatedAt(),
        ];
    }
}

Collection resolver with pagination

<?php

namespace Vendor\Module\Model\Resolver;

use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Query\ResolverInterface;
use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;
use Magento\Framework\Api\SearchCriteriaBuilder;

class Subscriptions implements ResolverInterface
{
    public function __construct(
        private \Vendor\Module\Api\SubscriptionRepositoryInterface $subscriptionRepository,
        private SearchCriteriaBuilder $searchCriteriaBuilder
    ) {}

    public function resolve(Field $field, mixed $context, ResolveInfo $info, ?array $value = null, ?array $args = null): array
    {
        $pageSize    = $args['pageSize'] ?? 20;
        $currentPage = $args['currentPage'] ?? 1;

        $sc     = $this->searchCriteriaBuilder->setPageSize($pageSize)->setCurrentPage($currentPage)->create();
        $result = $this->subscriptionRepository->getList($sc);

        return [
            'items'       => array_map(fn($s) => [
                'id'         => $s->getId(),
                'email'      => $s->getEmail(),
                'status'     => $s->getStatus(),
                'created_at' => $s->getCreatedAt(),
            ], $result->getItems()),
            'total_count' => $result->getTotalCount(),
            'page_info'   => [
                'page_size'    => $pageSize,
                'current_page' => $currentPage,
                'total_pages'  => (int) ceil($result->getTotalCount() / $pageSize),
            ],
        ];
    }
}

Authorization in resolvers

<?php

if (false === $context->getExtensionAttributes()->getIsCustomer()) {
    throw new \Magento\Framework\GraphQl\Exception\GraphQlAuthorizationException(
        __('The current customer isn\'t authorized.')
    );
}
$customerId = $context->getUserId();

Testing GraphQL in DDEV

curl -X POST https://magento2-dev.ddev.site/graphql \
  -H 'Content-Type: application/json' \
  -d '{"query":"{ products(search: \"test\", pageSize: 3) { items { name sku } } }"}'

Summary

GraphQL in Magento 2 is a solid REST alternative, especially for headless and PWA projects. The .graphqls schema clearly documents what the API exposes, resolvers implement exactly one contract, and the client fetches only the data it needs. If you are building with Vue Storefront or Magento PWA Studio – GraphQL is the natural choice.