git:20260309.786511c to git:20260914.08f85a3

---

name: magento-api

description: Build Magento 2 REST and GraphQL APIs — webapi.xml, schema.graphqls, resolvers, authentication, and ACL. Use when creating custom API endpoints, extending the GraphQL schema, or integrating external systems.

allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

---

# Magento 2 REST & GraphQL API Development

## Before writing code

**Fetch live docs**:

1. Fetch `https://developer.adobe.com/commerce/webapi/` for Web API overview

2. Fetch `https://developer.adobe.com/commerce/webapi/graphql/develop/` for GraphQL development guide

4. Web-search `site:developer.adobe.com commerce php development components web-api` for webapi.xml reference

## REST API

### How It Works

REST endpoints map HTTP methods + URL paths to service contract methods. Defined in `etc/webapi.xml`.

### webapi.xml Structure

Each route defines:

- `url` — endpoint path (e.g., `/V1/custom/items/:id`)

- `method` — HTTP method (GET, POST, PUT, DELETE)

- `service` — class + method implementing the endpoint

- `resource` — ACL resource for authorization

Path parameters (`:id`) map to method parameters by name.

### Authentication Types

| Type | Header | Use Case |

|------|--------|----------|

| **Admin Token** | `Authorization: Bearer <token>` | Back-office integrations |

| **Customer Token** | `Authorization: Bearer <token>` | Customer-facing apps |

| **OAuth 1.0a** | OAuth headers | Third-party integrations |

| **Session** | PHP session cookie | Storefront JS widgets |

| **Anonymous** | `resource="anonymous"` | Public endpoints |

### Swagger/OpenAPI

Available at `/rest/<store>/schema` — auto-generated from webapi.xml and service contracts.

## GraphQL API

### How It Works

GraphQL uses a single endpoint (`/graphql`) with schema files and resolver classes.

### Schema Files (schema.graphqls)

Define types, queries, and mutations in `etc/schema.graphqls`:

- Custom types with fields

- Query definitions mapping to resolver classes

- Mutation definitions with input/output types

- Extend existing types with new fields

### Resolver Classes

Implement `Magento\Framework\GraphQl\Query\ResolverInterface`:

- `resolve(Field $field, $context, ResolveInfo $info, array $value = null, array $args = null)`

- Return arrays matching the GraphQL type definition

- Context provides store, customer, and extension attributes

### Identity for Cache

Implement `Magento\Framework\GraphQl\Query\Resolver\IdentityInterface` for full-page cache invalidation of GraphQL responses.

### GraphQL Authorization

- Customer context via `Authorization: Bearer <customer-token>` header

- Admin context not supported in GraphQL (by design — GraphQL is storefront-facing)

- Use `$context->getExtensionAttributes()->getIsCustomer()` for auth checks

## ACL (Access Control List)

### acl.xml

Defines the resource tree for authorization:

- Nested `<resource>` elements form a hierarchy

- Referenced in `webapi.xml` via `<resource ref="Vendor_Module::resource_name"/>`

- Special values: `anonymous` (no auth), `self` (customer's own data)

## Best Practices

- Always define service contract interfaces first, then expose via webapi.xml

- Use ACL resources for all non-public endpoints

- Prefer GraphQL for storefront/headless, REST for integrations

- Return proper HTTP status codes (200, 201, 400, 401, 403, 404)

- Use SearchCriteria for list endpoints

- Add cache identity classes for GraphQL resolver performance

Fetch the Web API and GraphQL development docs for exact XML schema, resolver signatures, and authentication patterns before implementing.