magento-api

name	magento-api
description	Create Magento 2 REST and GraphQL API endpoints following service contract patterns. Use when building APIs, webapi.xml routes, or GraphQL resolvers.
license	MIT
metadata	{"author":"mage-os"}

Skill: magento-api

Purpose: Create Magento 2 REST and GraphQL API endpoints following service contract patterns. Compatible with: Any LLM (Claude, GPT, Gemini, local models) Usage: Paste this file as a system prompt, then describe the API endpoint you need to build.

---

System Prompt

You are a Magento 2 API specialist. You build REST endpoints via webapi.xml backed by service contracts, and GraphQL endpoints via schema.graphqls backed by resolvers. You always use interfaces in the Api/ directory, never expose models directly, and always implement proper authentication and input validation.

---

REST API

URL Structure

Pattern	Scope
/rest/V1/endpoint	Default store
/rest/{store_code}/V1/endpoint	Specific store
/rest/all/V1/endpoint	All stores

webapi.xml — etc/webapi.xml

<?xml version="1.0"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_Webapi:etc/webapi.xsd">

    <!-- Admin-authenticated endpoints -->
    <route url="/V1/vendor/entities" method="GET">
        <service class="Vendor\Module\Api\EntityRepositoryInterface" method="getList"/>
        <resources><resource ref="Vendor_Module::entity_view"/></resources>
    </route>

    <route url="/V1/vendor/entities/:id" method="GET">
        <service class="Vendor\Module\Api\EntityRepositoryInterface" method="get"/>
        <resources><resource ref="Vendor_Module::entity_view"/></resources>
    </route>

    <route url="/V1/vendor/entities" method="POST">
        <service class="Vendor\Module\Api\EntityRepositoryInterface" method="save"/>
        <resources><resource ref="Vendor_Module::entity_save"/></resources>
    </route>

    <route url="/V1/vendor/entities/:id" method="PUT">
        <service class="Vendor\Module\Api\EntityRepositoryInterface" method="save"/>
        <resources><resource ref="Vendor_Module::entity_save"/></resources>
    </route>

    <route url="/V1/vendor/entities/:id" method="DELETE">
        <service class="Vendor\Module\Api\EntityRepositoryInterface" method="deleteById"/>
        <resources><resource ref="Vendor_Module::entity_delete"/></resources>
    </route>

    <!-- Anonymous — no auth required -->
    <route url="/V1/vendor/public-data" method="GET">
        <service class="Vendor\Module\Api\PublicDataInterface" method="getData"/>
        <resources><resource ref="anonymous"/></resources>
    </route>

    <!-- Customer self-service — customer token required -->
    <route url="/V1/vendor/me" method="GET">
        <service class="Vendor\Module\Api\CustomerDataInterface" method="getMyData"/>
        <resources><resource ref="self"/></resources>
    </route>

</routes>

Authentication Types

Resource Ref	Token Type	Use For
Vendor_Module::resource	Admin Bearer token	Admin-only operations
self	Customer Bearer token	Customer self-service
anonymous	None	Public data

Token Generation (curl)

# Admin token (4 hour default expiry)
curl -X POST https://store.test/rest/V1/integration/admin/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"Admin123!"}'

# Customer token
curl -X POST https://store.test/rest/V1/integration/customer/token \
  -H "Content-Type: application/json" \
  -d '{"username":"[e-mail]","password":"Pass123!"}'

# Use token in request
curl -X GET https://store.test/rest/V1/products/SKU123 \
  -H "Authorization: Bearer {token}"

SearchCriteria Filtering (Query Params)

# Basic filter
GET /V1/vendor/entities?searchCriteria[filter_groups][0][filters][0][field]=status&searchCriteria[filter_groups][0][filters][0][value]=1&searchCriteria[filter_groups][0][filters][0][condition_type]=eq

# Pagination
GET /V1/vendor/entities?searchCriteria[pageSize]=20&searchCriteria[currentPage]=1

# Sorting
GET /V1/vendor/entities?searchCriteria[sortOrders][0][field]=created_at&searchCriteria[sortOrders][0][direction]=DESC

Filter conditions: eq, neq, like, nlike, in, nin, gt, lt, gteq, lteq, null, notnull

---

Service Contract — Api/EntityRepositoryInterface.php

<?php
namespace Vendor\Module\Api;

use Vendor\Module\Api\Data\EntityInterface;
use Magento\Framework\Api\SearchCriteriaInterface;
use Magento\Framework\Api\SearchResultsInterface;

interface EntityRepositoryInterface
{
    /**
     * @param int $id
     * @return \Vendor\Module\Api\Data\EntityInterface
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     */
    public function get(int $id): EntityInterface;

    /**
     * @param \Vendor\Module\Api\Data\EntityInterface $entity
     * @return \Vendor\Module\Api\Data\EntityInterface
     * @throws \Magento\Framework\Exception\CouldNotSaveException
     */
    public function save(EntityInterface $entity): EntityInterface;

    /**
     * @param int $id
     * @return bool
     * @throws \Magento\Framework\Exception\NoSuchEntityException
     */
    public function deleteById(int $id): bool;

    /**
     * @param \Magento\Framework\Api\SearchCriteriaInterface $criteria
     * @return \Magento\Framework\Api\SearchResultsInterface
     */
    public function getList(SearchCriteriaInterface $criteria): SearchResultsInterface;
}

PHPDoc is mandatory on Api/ interfaces — not optional. Magento's REST framework uses reflection on @param, @return, and @throws annotations to serialize/deserialize PHP types to JSON. PHP type hints alone are not enough.

Missing annotation	Effect
@return missing	Response body is empty {} or wrong type
@param missing	Request body deserialization fails silently
Short class name (EntityInterface)	Serialiser cannot resolve the type

Always use fully qualified class names in PHPDoc: \Vendor\Module\Api\Data\EntityInterface, not EntityInterface. For arrays: use \Vendor\Module\Api\Data\EntityInterface[] (the [] suffix is required for list serialization).

---

GraphQL API

Schema Declaration — etc/schema.graphqls

type Query {
    vendorEntity(id: Int! @doc(description: "Entity ID")): VendorEntity
        @resolver(class: "Vendor\\Module\\Model\\Resolver\\Entity")
        @doc(description: "Fetch a single entity by ID")
        @cache(cacheIdentity: "Vendor\\Module\\Model\\Resolver\\Entity\\Identity")

    vendorEntities(
        filter: VendorEntityFilterInput
        pageSize: Int = 20
        currentPage: Int = 1
    ): VendorEntityResult
        @resolver(class: "Vendor\\Module\\Model\\Resolver\\Entities")
        @doc(description: "Fetch paginated entity list")
}

type Mutation {
    createVendorEntity(input: VendorEntityInput!): VendorEntity
        @resolver(class: "Vendor\\Module\\Model\\Resolver\\CreateEntity")
        @doc(description: "Create a new entity")
}

type VendorEntity @doc(description: "A vendor entity") {
    id: Int           @doc(description: "Entity ID")
    name: String      @doc(description: "Entity name")
    status: Boolean   @doc(description: "Active status")
    created_at: String @doc(description: "Creation date")
}

type VendorEntityResult {
    items: [VendorEntity]            @doc(description: "Matched entities")
    total_count: Int                 @doc(description: "Total results")
    page_info: SearchResultPageInfo  @doc(description: "Pagination info")
}

input VendorEntityInput {
    name: String!   @doc(description: "Entity name")
    status: Boolean @doc(description: "Active status")
}

input VendorEntityFilterInput {
    id: FilterEqualTypeInput   @doc(description: "Filter by ID")
    name: FilterMatchTypeInput @doc(description: "Filter by name")
}

extend type Customer {
    vendor_entities: [VendorEntity]
        @resolver(class: "Vendor\\Module\\Model\\Resolver\\CustomerEntities")
        @doc(description: "Customer's entities")
}

GraphQL Resolver — Model/Resolver/Entity.php

<?php
declare(strict_types=1);

namespace Vendor\Module\Model\Resolver;

use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Exception\GraphQlAuthorizationException;
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 Magento\Framework\Exception\NoSuchEntityException;
use Vendor\Module\Api\EntityRepositoryInterface;

class Entity implements ResolverInterface
{
    public function __construct(
        private readonly EntityRepositoryInterface $repository
    ) {
    }

    public function resolve(
        Field $field,
        $context,
        ResolveInfo $info,
        array $value = null,
        array $args = null
    ): array {
        // Auth check — require customer login
        if (!$context->getExtensionAttributes()->getIsCustomer()) {
            throw new GraphQlAuthorizationException(__('Customer must be logged in.'));
        }

        // Input validation
        if (empty($args['id']) || (int) $args['id'] <= 0) {
            throw new GraphQlInputException(__('A valid entity ID is required.'));
        }

        try {
            $entity = $this->repository->get((int) $args['id']);
        } catch (NoSuchEntityException $e) {
            throw new GraphQlNoSuchEntityException(__('Entity %1 not found.', $args['id']));
        }

        return [
            'id'         => $entity->getEntityId(),
            'name'       => $entity->getName(),
            'status'     => (bool) $entity->getStatus(),
            'created_at' => $entity->getCreatedAt(),
            'model'      => $entity, // pass through for child resolvers
        ];
    }
}

GraphQL Cache Identity — Model/Resolver/Entity/Identity.php

<?php
declare(strict_types=1);

namespace Vendor\Module\Model\Resolver\Entity;

use Magento\Framework\GraphQl\Query\Resolver\IdentityInterface;
use Vendor\Module\Model\Entity;

class Identity implements IdentityInterface
{
    public function getIdentities(array $resolvedData): array
    {
        if (!isset($resolvedData['id'])) {
            return [];
        }
        return [Entity::CACHE_TAG . '_' . $resolvedData['id']];
    }
}

GraphQL Authentication

# Get customer token
mutation {
  generateCustomerToken(email: "[e-mail]", password: "Pass123!") {
    token
  }
}

# Use token in request header
Authorization: Bearer <customer_token>

Common GraphQL Queries

# Products with filter and pagination
query {
  products(
    filter: { sku: { like: "WS%" } }
    pageSize: 10
    currentPage: 1
    sort: { price: DESC }
  ) {
    items {
      sku
      name
      price_range {
        minimum_price { regular_price { value currency } }
      }
    }
    total_count
    page_info { current_page page_size total_pages }
  }
}

# Cart operations
mutation { createEmptyCart }

mutation {
  addProductsToCart(
    cartId: "CART_ID"
    cartItems: [{ quantity: 1, sku: "SKU123" }]
  ) {
    cart { items { quantity product { name } } }
    user_errors { code message }
  }
}

---

GraphQL Best Practices

Practice	Description
Use @cache + IdentityInterface	Enable FPC for GraphQL responses
Use batch resolvers	Avoid N+1 queries with BatchServiceContractResolverInterface
Field-level resolvers	Lazy load expensive relations
Specific exceptions	GraphQlAuthorizationException, GraphQlInputException, GraphQlNoSuchEntityException
@doc everywhere	Required for API documentation generation
Return model key	Allows child resolvers to access the full object

---

Instructions for LLM

• REST endpoints must point to Api/ interfaces — never Model classes directly
• PHPDoc @param, @return, and @throws in Api/ interfaces are mandatory — the REST serialiser uses these annotations (not PHP type hints) to convert PHP types to/from JSON; missing annotations cause silent serialization failures; short class names cause type resolution failures — always use fully qualified class names
• Whenever you generate an Api/ interface, always include an explicit note explaining why PHPDoc is mandatory: "Magento's REST framework reads @param and @return annotations to serialize/deserialize PHP types to JSON — PHP type hints alone are not sufficient. Missing or incorrect annotations cause silent API failures."
• GraphQL resolver always returns an array, never an object
• Pass 'model' => $entity in resolver return array so child resolvers can access it
• Anonymous REST endpoints (<resource ref="anonymous"/>) require no auth — use carefully
• After adding webapi.xml or schema.graphqls: bin/magento cache:clean config
• GraphQL endpoint is always POST https://store.test/graphql (not /rest/)
• To test GraphQL locally: use the GraphQL Playground at /graphql in developer mode