Magento 2 REST & GraphQL API Development
Before writing code
Fetch live docs:
- Fetch
https://developer.adobe.com/commerce/webapi/ for Web API overview
- Fetch
https://developer.adobe.com/commerce/webapi/graphql/develop/ for GraphQL development guide
- Fetch
https://developer.adobe.com/commerce/webapi/get-started/ for authentication
- 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.
1---2name: magento-api3description: 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.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/magento-api7---89# Magento 2 REST & GraphQL API Development1011## Before writing code1213**Fetch live docs**:141. Fetch `https://developer.adobe.com/commerce/webapi/` for Web API overview152. Fetch `https://developer.adobe.com/commerce/webapi/graphql/develop/` for GraphQL development guide163. Fetch `https://developer.adobe.com/commerce/webapi/get-started/` for authentication174. Web-search `site:developer.adobe.com commerce php development components web-api` for webapi.xml reference1819## REST API2021### How It Works2223REST endpoints map HTTP methods + URL paths to service contract methods. Defined in `etc/webapi.xml`.2425### webapi.xml Structure2627Each route defines:28- `url` — endpoint path (e.g., `/V1/custom/items/:id`)29- `method` — HTTP method (GET, POST, PUT, DELETE)30- `service` — class + method implementing the endpoint31- `resource` — ACL resource for authorization3233Path parameters (`:id`) map to method parameters by name.3435### Authentication Types3637| Type | Header | Use Case |38|------|--------|----------|39| **Admin Token** | `Authorization: Bearer <token>` | Back-office integrations |40| **Customer Token** | `Authorization: Bearer <token>` | Customer-facing apps |41| **OAuth 1.0a** | OAuth headers | Third-party integrations |42| **Session** | PHP session cookie | Storefront JS widgets |43| **Anonymous** | `resource="anonymous"` | Public endpoints |4445### Swagger/OpenAPI4647Available at `/rest/<store>/schema` — auto-generated from webapi.xml and service contracts.4849## GraphQL API5051### How It Works5253GraphQL uses a single endpoint (`/graphql`) with schema files and resolver classes.5455### Schema Files (schema.graphqls)5657Define types, queries, and mutations in `etc/schema.graphqls`:58- Custom types with fields59- Query definitions mapping to resolver classes60- Mutation definitions with input/output types61- Extend existing types with new fields6263### Resolver Classes6465Implement `Magento\Framework\GraphQl\Query\ResolverInterface`:66- `resolve(Field $field, $context, ResolveInfo $info, array $value = null, array $args = null)`67- Return arrays matching the GraphQL type definition68- Context provides store, customer, and extension attributes6970### Identity for Cache7172Implement `Magento\Framework\GraphQl\Query\Resolver\IdentityInterface` for full-page cache invalidation of GraphQL responses.7374### GraphQL Authorization7576- Customer context via `Authorization: Bearer <customer-token>` header77- Admin context not supported in GraphQL (by design — GraphQL is storefront-facing)78- Use `$context->getExtensionAttributes()->getIsCustomer()` for auth checks7980## ACL (Access Control List)8182### acl.xml8384Defines the resource tree for authorization:85- Nested `<resource>` elements form a hierarchy86- Referenced in `webapi.xml` via `<resource ref="Vendor_Module::resource_name"/>`87- Special values: `anonymous` (no auth), `self` (customer's own data)8889## Best Practices9091- Always define service contract interfaces first, then expose via webapi.xml92- Use ACL resources for all non-public endpoints93- Prefer GraphQL for storefront/headless, REST for integrations94- Return proper HTTP status codes (200, 201, 400, 401, 403, 404)95- Use SearchCriteria for list endpoints96- Add cache identity classes for GraphQL resolver performance9798Fetch the Web API and GraphQL development docs for exact XML schema, resolver signatures, and authentication patterns before implementing.