gabrielmoreira AEM Content API & Headless
Purpose
Implement headless content delivery using AEM's GraphQL API, Content Services, and Content Fragment APIs for decoupled frontend architectures and multi-channel distribution.
When to Use (Triggers)
- User mentions "headless," "GraphQL," "Content Services," or "content API"
- References to Content Fragment delivery, persisted queries, or API endpoints
- Questions about SPA Editor, remote SPA, or decoupled frontend architecture
- Requests involving JSON delivery, REST endpoints for content, or SDK usage
- Discussion of AEM as a headless CMS or content-as-a-service patterns
Core Capabilities
- Configure and optimize GraphQL persisted queries for Content Fragment delivery
- Implement Content Services (JSON Exporter) for page-based content APIs
- Set up AEM Headless SDK integration for JavaScript/React/Angular frontends
- Design Content Fragment Model schemas for API-first content delivery
- Configure CORS, authentication, and caching for headless endpoints
Domain Knowledge Required
Technical Foundation
- GraphQL schema design (types, queries, fragments, pagination, filtering)
- REST API design principles and JSON:API patterns
- CORS configuration and pre-flight request handling
- CDN caching strategies for API responses (Cache-Control, ETag, Vary)
AEM-Specific Context
- AEM GraphQL API endpoint structure and persisted queries
- Content Fragment Model to GraphQL schema mapping
- Sling Model Exporter (@Exporter annotation) for JSON serialization
- AEM Headless SDK (JavaScript, Java, iOS, Android)
- Universal Editor and Remote SPA Editor integration
Implementation Approach
Step 1: Content Model Design for API
Design Content Fragment Models optimized for API consumption.
- Define models with API consumers in mind (field naming, nesting depth)
- Plan reference resolution strategy (inline vs. linked)
- Configure model field types for optimal serialization (JSON, multi-value)
- Design fragment relationships for query efficiency
Step 2: GraphQL Configuration
Set up GraphQL endpoints and persisted queries.
- Create GraphQL endpoints for each site/project
- Write and persist common queries for frontend consumption
- Configure query complexity limits and depth restrictions
- Set up filtering, pagination, and sorting capabilities
Step 3: Authentication & Security
Secure headless API access.
- Configure CORS policies for allowed origins
- Set up token-based authentication (service credentials, IMS tokens)
- Implement API rate limiting and throttling
- Configure CDN-level security (WAF rules, IP allowlisting)
Step 4: Caching & Performance
Optimize API response performance.
- Configure CDN caching for persisted query responses
- Implement cache invalidation on content publish
- Set up ETags and conditional requests
- Design query patterns that minimize response size
Step 5: Frontend Integration
Connect frontend applications to AEM headless.
- Integrate AEM Headless SDK in frontend framework
- Implement content preview and editing capabilities
- Configure environment-specific endpoint configuration
- Set up error handling and retry logic for API calls
Quality Checklist
- GraphQL persisted queries return expected data structure
- CORS configured for all required frontend origins
- API responses cached at CDN with appropriate TTL
- Cache invalidation triggers on content publish
- Authentication tokens validated and refreshed correctly
- API response times under 200ms for common queries (cached)
- Error responses follow consistent format with actionable messages
- Content preview works for unpublished content in author mode
Related Skills
- aem-content-strategy-architecture (content model design)
- aem-caching-strategy (API caching)
- aem-dispatcher-configuration (API routing and caching at dispatcher)
Example Use Cases
- React SPA with AEM Backend: Build a single-page application consuming Content Fragments via GraphQL persisted queries with real-time preview in AEM author using Universal Editor.
- Mobile App Content Feed: Deliver personalized content to iOS/Android apps using AEM Headless SDK with offline caching, pagination, and push-notification-triggered content refresh.
- Multi-Channel Content Hub: Serve identical content to web, digital signage, chatbot, and email systems through a unified GraphQL API with channel-specific field selection and transformation.
Notes
- Persisted queries are production-recommended — avoid runtime query execution for performance
- AEM Cloud Service has built-in CDN for GraphQL endpoints — leverage it rather than adding custom CDN
- Content Fragment references resolve up to 10 levels deep by default — design shallow hierarchies
- GraphQL API only serves published content on publish tier — use author endpoint for preview