REST and GraphQL APIs

app/code/PocketCoffee/Api/
├── registration.php
├── composer.json
├── Api/
│   ├── Data/RoastBatchInterface.php
│   ├── GreetingInterface.php
│   └── RoastBatchRepositoryInterface.php
├── Model/
│   ├── Greeting.php
│   ├── RoastBatch.php
│   ├── RoastBatchRepository.php
│   └── Resolver/{RoastBatch,SetRoastBatch,ProductRoastDateBatch}.php
├── ViewModel/RoastBadge.php
├── etc/
│   ├── module.xml
│   ├── db_schema.xml
│   ├── db_schema_whitelist.json
│   ├── acl.xml
│   ├── di.xml
│   ├── webapi.xml
│   └── schema.graphqls
└── view/frontend/{layout,templates}/...

<?php
declare(strict_types=1);

namespace PocketCoffee\Api\Api\Data;

/**
 * A roast batch of a product.
 *
 * @api
 */
interface RoastBatchInterface
{
    /**
     * @return string
     */
    public function getSku(): string;

    /**
     * @param string $sku
     * @return $this
     */
    public function setSku(string $sku): self;

    /**
     * @return string Roast date as YYYY-MM-DD
     */
    public function getRoastDate(): string;

    /**
     * @param string $roastDate Roast date as YYYY-MM-DD
     * @return $this
     */
    public function setRoastDate(string $roastDate): self;

    /**
     * @return string|null
     */
    public function getOrigin(): ?string;

    /**
     * @param string|null $origin
     * @return $this
     */
    public function setOrigin(?string $origin): self;
}

<?php
declare(strict_types=1);

namespace PocketCoffee\Api\Api;

use Magento\Framework\Exception\CouldNotSaveException;
use Magento\Framework\Exception\NoSuchEntityException;
use PocketCoffee\Api\Api\Data\RoastBatchInterface;

/**
 * Roast batch repository.
 *
 * @api
 */
interface RoastBatchRepositoryInterface
{
    /**
     * Get the roast batch of a SKU.
     *
     * @param string $sku
     * @return \PocketCoffee\Api\Api\Data\RoastBatchInterface
     * @throws NoSuchEntityException
     */
    public function get(string $sku): RoastBatchInterface;

    /**
     * Create or replace a roast batch.
     *
     * @param \PocketCoffee\Api\Api\Data\RoastBatchInterface $batch
     * @return \PocketCoffee\Api\Api\Data\RoastBatchInterface
     * @throws CouldNotSaveException
     */
    public function save(RoastBatchInterface $batch): RoastBatchInterface;

    /**
     * Delete the roast batch of a SKU.
     *
     * @param string $sku
     * @return bool
     * @throws NoSuchEntityException
     */
    public function deleteBySku(string $sku): bool;
}

<?php
declare(strict_types=1);

namespace PocketCoffee\Api\Model;

use Magento\Framework\App\ResourceConnection;
use Magento\Framework\Exception\CouldNotSaveException;
use Magento\Framework\Exception\InputException;
use Magento\Framework\Exception\NoSuchEntityException;
use PocketCoffee\Api\Api\Data\RoastBatchInterface;
use PocketCoffee\Api\Api\Data\RoastBatchInterfaceFactory;
use PocketCoffee\Api\Api\RoastBatchRepositoryInterface;

class RoastBatchRepository implements RoastBatchRepositoryInterface
{
    private const TABLE = 'pocketcoffee_api_roast_batch';

    public function __construct(
        private readonly ResourceConnection $resource,
        private readonly RoastBatchInterfaceFactory $factory
    ) {
    }

    public function get(string $sku): RoastBatchInterface
    {
        $connection = $this->resource->getConnection();
        $row = $connection->fetchRow(
            $connection->select()->from($this->resource->getTableName(self::TABLE))->where('sku = ?', $sku)
        );
        if (!$row) {
            throw new NoSuchEntityException(__('No roast batch for SKU "%1".', $sku));
        }
        return $this->factory->create(['data' => $row]);
    }

    public function save(RoastBatchInterface $batch): RoastBatchInterface
    {
        if (!preg_match('/^\d{4}-\d{2}-\d{2}$/', $batch->getRoastDate())) {
            throw new InputException(__('"%fieldName" must be a date as YYYY-MM-DD.', ['fieldName' => 'roast_date']));
        }
        try {
            $this->resource->getConnection()->insertOnDuplicate(
                $this->resource->getTableName(self::TABLE),
                ['sku' => $batch->getSku(), 'roast_date' => $batch->getRoastDate(), 'origin' => $batch->getOrigin()],
                ['roast_date', 'origin']
            );
        } catch (\Exception $e) {
            throw new CouldNotSaveException(__('The roast batch could not be saved.'), $e);
        }
        return $this->get($batch->getSku());
    }

    public function deleteBySku(string $sku): bool
    {
        $this->get($sku);
        $this->resource->getConnection()->delete(
            $this->resource->getTableName(self::TABLE),
            ['sku = ?' => $sku]
        );
        return true;
    }
}

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
    <preference for="PocketCoffee\Api\Api\Data\RoastBatchInterface" type="PocketCoffee\Api\Model\RoastBatch"/>
    <preference for="PocketCoffee\Api\Api\RoastBatchRepositoryInterface" type="PocketCoffee\Api\Model\RoastBatchRepository"/>
    <preference for="PocketCoffee\Api\Api\GreetingInterface" type="PocketCoffee\Api\Model\Greeting"/>
</config>

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">
    <!-- Public read: anyone may ask when a SKU was roasted -->
    <route url="/V1/pocketcoffee/roast-batches/:sku" method="GET">
        <service class="PocketCoffee\Api\Api\RoastBatchRepositoryInterface" method="get"/>
        <resources>
            <resource ref="anonymous"/>
        </resources>
    </route>
    <!-- Write: admin tokens or integrations that were granted the ACL resource -->
    <route url="/V1/pocketcoffee/roast-batches" method="POST">
        <service class="PocketCoffee\Api\Api\RoastBatchRepositoryInterface" method="save"/>
        <resources>
            <resource ref="PocketCoffee_Api::roast_batches_manage"/>
        </resources>
    </route>
    <route url="/V1/pocketcoffee/roast-batches/:sku" method="DELETE">
        <service class="PocketCoffee\Api\Api\RoastBatchRepositoryInterface" method="deleteBySku"/>
        <resources>
            <resource ref="PocketCoffee_Api::roast_batches_manage"/>
        </resources>
    </route>
    <!-- Customer self-service: the customer id comes from the token, never from the client -->
    <route url="/V1/pocketcoffee/me/greeting" method="GET">
        <service class="PocketCoffee\Api\Api\GreetingInterface" method="forCustomer"/>
        <resources>
            <resource ref="self"/>
        </resources>
        <data>
            <parameter name="customerId" force="true">%customer_id%</parameter>
        </data>
    </route>
</routes>

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Acl/etc/acl.xsd">
    <acl>
        <resources>
            <resource id="Magento_Backend::admin">
                <resource id="Magento_Catalog::catalog">
                    <resource id="PocketCoffee_Api::roast_batches" title="Pocket Coffee roast batches" sortOrder="200">
                        <resource id="PocketCoffee_Api::roast_batches_manage" title="Manage roast batches" sortOrder="10"/>
                    </resource>
                </resource>
            </resource>
        </resources>
    </acl>
</config>

# Write: requires the ACL resource PocketCoffee_Api::roast_batches_manage
curl -s -X POST http://localhost:8082/rest/V1/pocketcoffee/roast-batches \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" -H 'Content-Type: application/json' \
  -d '{"batch":{"sku":"PC-ETH-WHL-250","roast_date":"2026-10-20","origin":"Ethiopia Yirgacheffe"}}'
# {"sku":"PC-ETH-WHL-250","roast_date":"2026-10-20","origin":"Ethiopia Yirgacheffe"}

# Read: anonymous
curl -s http://localhost:8082/rest/V1/pocketcoffee/roast-batches/PC-ETH-WHL-250
curl -s -H 'Accept: application/xml' http://localhost:8082/rest/V1/pocketcoffee/roast-batches/PC-ETH-WHL-250
# <response><sku>PC-ETH-WHL-250</sku><roast_date>2026-10-20</roast_date><origin>Ethiopia Yirgacheffe</origin></response>

# Delete
curl -s -X DELETE http://localhost:8082/rest/V1/pocketcoffee/roast-batches/PC-ETH-WHL-1KG \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"
# true

curl -s -g "http://localhost:8082/rest/V1/products?searchCriteria[filter_groups][0][filters][0][field]=sku&searchCriteria[filter_groups][0][filters][0][value]=POCKET%25&searchCriteria[filter_groups][0][filters][0][condition_type]=like&searchCriteria[sortOrders][0][field]=name&searchCriteria[pageSize]=5&fields=items[sku,price],total_count" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"
# {"items":[{"sku":"POCKET-001","price":3.5}],"total_count":1}

# Copyright (c) Pocket Coffee example. Licensed under OSL-3.0.

type Query {
    pocketCoffeeRoastBatch(sku: String! @doc(description: "Product SKU")): PocketCoffeeRoastBatch
        @resolver(class: "PocketCoffee\\Api\\Model\\Resolver\\RoastBatch")
        @doc(description: "Returns the current roast batch of a SKU")
        @cache(cacheable: false)
}

type Mutation {
    setPocketCoffeeRoastBatch(input: PocketCoffeeRoastBatchInput!): PocketCoffeeRoastBatch
        @resolver(class: "PocketCoffee\\Api\\Model\\Resolver\\SetRoastBatch")
        @doc(description: "Creates or replaces the roast batch of a SKU. Requires an admin token with the manage ACL resource.")
}

input PocketCoffeeRoastBatchInput {
    sku: String! @doc(description: "Product SKU")
    roast_date: String! @doc(description: "Roast date, YYYY-MM-DD")
    origin: String @doc(description: "Origin of the beans")
}

type PocketCoffeeRoastBatch @doc(description: "A roast batch") {
    sku: String
    roast_date: String
    origin: String
}

interface ProductInterface {
    roast_date: String @doc(description: "Roast date of the product") @resolver(class: "PocketCoffee\\Api\\Model\\Resolver\\ProductRoastDateBatch")
}

<?php
declare(strict_types=1);

namespace PocketCoffee\Api\Model\Resolver;

use Magento\Framework\Exception\NoSuchEntityException;
use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Exception\GraphQlInputException;
use Magento\Framework\GraphQl\Exception\GraphQlNoSuchEntityException;
use Magento\Framework\GraphQl\Query\ResolverInterface;
use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;
use PocketCoffee\Api\Api\RoastBatchRepositoryInterface;

class RoastBatch implements ResolverInterface
{
    public function __construct(private readonly RoastBatchRepositoryInterface $repository)
    {
    }

    public function resolve(Field $field, $context, ResolveInfo $info, ?array $value = null, ?array $args = null)
    {
        if (empty($args['sku'])) {
            throw new GraphQlInputException(__('"sku" value must be specified.'));
        }
        try {
            $batch = $this->repository->get($args['sku']);
        } catch (NoSuchEntityException $e) {
            throw new GraphQlNoSuchEntityException(__($e->getMessage()), $e);
        }
        return ['sku' => $batch->getSku(), 'roast_date' => $batch->getRoastDate(), 'origin' => $batch->getOrigin()];
    }
}

<?php
declare(strict_types=1);

namespace PocketCoffee\Api\Model\Resolver;

use Magento\Authorization\Model\UserContextInterface;
use Magento\Framework\AuthorizationInterface;
use Magento\Framework\Exception\LocalizedException;
use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Exception\GraphQlAuthorizationException;
use Magento\Framework\GraphQl\Exception\GraphQlInputException;
use Magento\Framework\GraphQl\Query\ResolverInterface;
use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;
use PocketCoffee\Api\Api\Data\RoastBatchInterfaceFactory;
use PocketCoffee\Api\Api\RoastBatchRepositoryInterface;

class SetRoastBatch implements ResolverInterface
{
    public function __construct(
        private readonly RoastBatchRepositoryInterface $repository,
        private readonly RoastBatchInterfaceFactory $factory,
        private readonly AuthorizationInterface $authorization
    ) {
    }

    public function resolve(Field $field, $context, ResolveInfo $info, ?array $value = null, ?array $args = null)
    {
        if ($context->getUserType() !== UserContextInterface::USER_TYPE_ADMIN
            && $context->getUserType() !== UserContextInterface::USER_TYPE_INTEGRATION
        ) {
            throw new GraphQlAuthorizationException(__('An admin or integration token is required.'));
        }
        if (!$this->authorization->isAllowed('PocketCoffee_Api::roast_batches_manage')) {
            throw new GraphQlAuthorizationException(__('The token may not manage roast batches.'));
        }
        $input = $args['input'] ?? [];
        try {
            $batch = $this->factory->create()
                ->setSku($input['sku'])
                ->setRoastDate($input['roast_date'])
                ->setOrigin($input['origin'] ?? null);
            $saved = $this->repository->save($batch);
        } catch (LocalizedException $e) {
            throw new GraphQlInputException(__($e->getMessage()), $e);
        }
        return ['sku' => $saved->getSku(), 'roast_date' => $saved->getRoastDate(), 'origin' => $saved->getOrigin()];
    }
}

<?php
declare(strict_types=1);

namespace PocketCoffee\Api\Model\Resolver;

use Magento\Framework\App\ResourceConnection;
use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Query\Resolver\BatchResolverInterface;
use Magento\Framework\GraphQl\Query\Resolver\BatchResponse;
use Magento\Framework\GraphQl\Query\Resolver\ContextInterface;

class ProductRoastDateBatch implements BatchResolverInterface
{
    public function __construct(private readonly ResourceConnection $resource)
    {
    }

    public function resolve(ContextInterface $context, Field $field, array $requests): BatchResponse
    {
        $skus = [];
        foreach ($requests as $request) {
            $skus[] = (string)$request->getValue()['model']->getSku();
        }
        $connection = $this->resource->getConnection();
        $dates = $connection->fetchPairs(
            $connection->select()
                ->from($this->resource->getTableName('pocketcoffee_api_roast_batch'), ['sku', 'roast_date'])
                ->where('sku IN (?)', array_unique($skus))
        );
        $response = new BatchResponse();
        foreach ($requests as $request) {
            $sku = (string)$request->getValue()['model']->getSku();
            $response->addResponse($request, $dates[$sku] ?? null);
        }
        return $response;
    }
}

# query, anonymous
curl -s -X POST http://localhost:8082/graphql -H 'Content-Type: application/json' \
  -d '{"query":"{ pocketCoffeeRoastBatch(sku: \"PC-ETH-WHL-250\") { sku roast_date origin } }"}'
# {"data":{"pocketCoffeeRoastBatch":{"sku":"PC-ETH-WHL-250","roast_date":"2026-10-20","origin":"Ethiopia Yirgacheffe"}}}

# mutation without a token: HTTP 200 and an error
# {"errors":[{"message":"An admin or integration token is required.", ..., "extensions":{"category":"graphql-authorization"}}],
#  "data":{"setPocketCoffeeRoastBatch":null}}

# mutation with an admin token
curl -s -X POST http://localhost:8082/graphql -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -d '{"query":"mutation { setPocketCoffeeRoastBatch(input:{sku:\"PC-BRA-ESP-1KG\", roast_date:\"2026-10-22\", origin:\"Brazil Cerrado\"}) { sku roast_date origin } }"}'
# {"data":{"setPocketCoffeeRoastBatch":{"sku":"PC-BRA-ESP-1KG","roast_date":"2026-10-22","origin":"Brazil Cerrado"}}}

# the extended product type, with the batch resolver
curl -s -X POST http://localhost:8082/graphql -H 'Content-Type: application/json' \
  -d '{"query":"{ products(filter:{sku:{in:[\"POCKET-001\",\"PC-ETH-WHL-250\"]}}) { items { sku roast_date } } }"}'
# {"data":{"products":{"items":[{"sku":"PC-ETH-WHL-250","roast_date":"2026-10-20"},{"sku":"POCKET-001","roast_date":"2026-10-25"}]}}}

# variables work as in any GraphQL server
curl -s -X POST http://localhost:8082/graphql -H 'Content-Type: application/json' \
  -d '{"query":"query($s:String!){ pocketCoffeeRoastBatch(sku:$s){sku roast_date} }","variables":{"s":"PC-ETH-WHL-250"}}'