magento-api-developer — Claude Code skill
magento-api-developer teaches the agent to design and write Magento 2 REST and GraphQL APIs: service contracts, DTOs, auth and tests.
MIT 259 installs ★ 33 updated 2026-01-24
npx skills add maxnorm/magento2-agent-skills --skill magento-api-developer -a claude-codeWhat magento-api-developer does
The skill briefs the agent on how Magento 2 APIs are put together: service contracts, DTOs, repositories, REST controllers, GraphQL resolvers. One SKILL.md file holds the whole playbook, from endpoint planning to tests and docs.
Work is split into four stages. Requirements and the data model come first, then interfaces under Api/, then implementation, then unit and integration tests. Separate sections cover e-commerce scenarios: products, orders, customers, stock, payments. GraphQL gets product queries, cart mutations and search resolvers, and there are admin APIs for bulk jobs and reporting.
Performance and security have their own guidance: pagination, field selection, response caching, OAuth 2.0 and JWT, rate limiting, CORS. Everything here is written instruction rather than a code generator, so name the module and entities you are working on. Leave that out and the agent starts guessing at class names.
What it helps with
- design a service contract and DTOs for a new module
- wire a GraphQL resolver for products with nested options
- build a checkout REST endpoint with correct status codes
- add OAuth 2.0 and JWT for a partner integration
- fix N+1 queries in cart requests and add pagination
Example prompts for the agent
- Design a service contract under
Api/and the DTOs for a reviews module in Magento 2 - Add a GraphQL resolver for products with nested options and response caching
- Sketch the checkout REST endpoint: route, status codes and input validation
How to install magento-api-developer
1Skills CLI (Vercel)
npx skills add maxnorm/magento2-agent-skills --skill magento-api-developer -a claude-code2Manually: put the files in place
~/.claude/skills/magento-api-developer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/magento-api-developer/
1Skills CLI (Vercel)
npx skills add maxnorm/magento2-agent-skills --skill magento-api-developer -a codex2Manually: put the files in place
.agents/skills/magento-api-developer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add maxnorm/magento2-agent-skills --skill magento-api-developer -a cursor2Manually: put the files in place
.cursor/skills/magento-api-developer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install maxnorm/magento2-agent-skills skills/magento-api-developer2Manually: put the files in place
.github/skills/magento-api-developer/SKILL.md1Skills CLI (Vercel)
npx skills add maxnorm/magento2-agent-skills --skill magento-api-developer -a gemini-cli2Platform CLI
gemini skills install https://github.com/maxnorm/magento2-agent-skills --path skills/magento-api-developerManually: put the files in place
.devin/skills/magento-api-developer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add maxnorm/magento2-agent-skills --skill magento-api-developer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about magento-api-developer
How do I install magento-api-developer in Claude Code?
Run npx skills add maxnorm/magento2-agent-skills --skill magento-api-developer -a claude-code. The skill file lands at ~/.claude/skills/magento-api-developer/SKILL.md.
What does magento-api-developer do?
It tells the agent how to design and implement Magento 2 REST and GraphQL APIs: service contracts, DTOs, endpoints, error handling and tests.
Does the skill cover headless storefronts?
Yes. It covers GraphQL product queries and cart mutations, and REST endpoints for mobile apps and third-party systems.
Source text
SKILL.md · MIT
--- name: magento-api-developer description: Designs and implements REST and GraphQL APIs for Magento 2. Use when developing APIs, creating service contracts, building headless commerce solutions, or integrating with external systems. Masters service contracts, data transfer objects, authentication, and enterprise-grade API architecture. --- # Magento 2 API Developer Expert specialist in designing and implementing robust, scalable REST and GraphQL APIs that serve as reliable data interfaces for headless commerce, mobile applications, and third-party integrations. ## When to Use - Developing REST or GraphQL APIs - Creating service contracts - Building headless commerce solutions - Integrating with external systems - Implementing API authentication and authorization - Designing data transfer objects ## API Architecture ### Service Contracts - Design clean, versioned API interfaces - Create data transfer objects (DTOs) for data exchange - Implement repository pattern for data access - Maintain backward compatibility ### REST API Design - Implement RESTful endpoints following industry best practices - Use proper HTTP methods (GET, POST, PUT, DELETE) - Design consistent URL structures - Implement proper status codes ### GraphQL Implementation - Build efficient GraphQL schemas and resolvers - Optimize query complexity - Implement proper caching strategies - Handle nested relationships efficiently ## API Development Process ### 1. API Planning & Design - **Requirements Analysis**: Gather API requirements from stakeholders - **Data Modeling**: Design data structures and entity relationships - **Endpoint Architecture**: Plan REST endpoints and GraphQL schema structure - **Security Design**: Plan authentication, authorization, and data protection - **Performance Planning**: Design for scalability and optimal response times ### 2. Service Contract Definition - **Interface Design**: Create comprehensive service interfaces in `Api/` directory - **Data Contract Specification**: Define DTOs and data structures - **Error Handling**: Design consistent error response patterns - **Validation Rules**: Implement robust input validation and sanitization - **Documentation**: Create comprehensive API documentation ### 3. Implementation Development - **Endpoint Implementation**: Build REST controllers and GraphQL resolvers - **Business Logic**: Implement service layer business logic - **Data Access**: Create repository implementations for data operations - **Response Formatting**: Ensure consistent response structures - **Error Handling**: Implement comprehensive error handling and logging ### 4. Testing & Quality Assurance - **Unit Testing**: Write comprehensive tests for service and repository layers - **Integration Testing**: Test complete API workflows and data flow - **Performance Testing**: Validate API performance under load - **Security Testing**: Test authentication, authorization, and data protection - **Documentation Testing**: Ensure API documentation accuracy ## API Types ### E-commerce REST APIs - **Product Management**: Product CRUD operations, catalog management - **Order Processing**: Order creation, updates, and fulfillment workflows - **Customer Management**: Customer registration, authentication, and profile management - **Inventory Operations**: Stock management, reservations, and availability - **Payment Processing**: Payment method integration and transaction handling ### GraphQL Schema Development - **Product Queries**: Efficient product data retrieval with nested relationships - **Cart Operations**: Shopping cart mutations and real-time updates - **Customer Queries**: Customer data and order history with fine-grained control - **Search Resolvers**: Advanced search and filtering capabilities - **Performance Optimization**: Query complexity analysis and caching strategies ### Administrative APIs - **Admin Operations**: Backend management and configuration APIs - **Bulk Operations**: Mass data import/export and batch processing - **Reporting APIs**: Data analytics and business intelligence endpoints - **System Configuration**: Dynamic configuration management APIs - **User Management**: Admin user and role management interfaces ## Advanced Techniques ### Performance Optimization - **Query Optimization**: Efficient database queries and N+1 problem resolution - **Caching Strategies**: Implement API response caching and cache invalidation - **Pagination**: Efficient large dataset pagination and cursor-based navigation - **Field Selection**: Allow clients to specify required fields for optimization - **Batch Operations**: Implement batch endpoints for bulk operations ### Security Implementation - **Authentication Methods**: OAuth 2.0, JWT tokens, and API key management - **Authorization Patterns**: Role-based and resource-based access control - **Rate Limiting**: Implement API throttling and abuse prevention - **Input Validation**: Comprehensive input sanitization and validation - **CORS Management**: Proper cross-origin resource sharing configuration ### Error Handling & Monitoring - **Consistent Error Responses**: Standardized error format and HTTP status codes - **Logging Strategy**: Comprehensive API request and error logging - **Monitoring Integration**: API performance and health monitoring - **Alert Systems**: Automated alerting for API issues and anomalies - **Debugging Tools**: Debug logging and request tracing capabilities ## Best Practices ### Design Principles - **Resource-Oriented Design**: Design APIs around resources and collections - **Stateless Operations**: Ensure API operations are stateless and idempotent - **Consistency**: Maintain consistent naming, patterns, and response formats - **Simplicity**: Provide simple, intuitive interfaces for common operations - **Flexibility**: Design for extensibility and future requirements ### Documentation & Developer Experience - **Interactive Documentation**: Provide Swagger/OpenAPI interactive documentation - **Code Examples**: Include practical examples in multiple programming languages - **SDKs & Libraries**: Provide client libraries for popular programming languages - **Sandbox Environment**: Offer testing environments for API consumers - **Developer Support**: Establish support channels and community resources ## References - [Adobe Commerce REST APIs](https://developer.adobe.com/commerce/web-api/rest/) - [Adobe Commerce GraphQL](https://developer.adobe.com/commerce/web-api/graphql/) - [Service Contracts](https://developer.adobe.com/commerce/php/development/components/service-contracts/) Focus on creating APIs that meet current integration needs while providing a foundation for future digital commerce innovations.
© maxnorm · MIT · maxnorm/magento2-agent-skills