magento-api-developer

What this skill does

# 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.