Blog posts by Michał Mitas

Blog posts by Michał Mitas2026-01-26T00:00:00.0000000Zhttps://world.optimizely.com/blogs/micha-mitas/ Optimizely World Building AI-Powered Tools with Optimizely Opal - A Step-by-Step GuideLearn how to build and integrate custom tools with Optimizely Opal using the Opal Tools SDK. This tutorial walks through creating tools, handling authorization, and leveraging AI reasoning.2026-01-26T00:00:00.0000000Z

Blog post

2025 Wrapped: Optimizely's Year of AI Acceleration and Opal MomentumA look back at Optimizely's most transformative year yet, with Opal at the center - and what's coming next in 2026.2025-12-29T00:00:00.0000000Z

Blog post

Going Headless: 3 Ways to Store Custom Data in Optimizely GraphWelcome to another installment of my Going Headless series. Previously, we covered: <ul> <li><a href="/link/e41f24d11ff7488db0b8ccc26b9711a7.aspx">Going Headless: Making the Right Architectural Choices</a></li> <li><a href="/link/425ad6b768e94410ab706643559c4f96.aspx">Going Headless: On-Page Editing with Optimizely Graph and Next.js</a></li> <li><a href="/link/c4887f08a93144b19377f27068985f71.aspx">Going Headless: Optimizely Graph vs Content Delivery API</a></li> </ul> So far, we've talked about architectural decisions, on-page editing, and how Optimizely Graph compares to other APIs. Today, we'll take the next step and look at how to store and expose your custom data in Optimizely Graph — data that doesn't necessarily come directly from CMS properties. This article walks through three different approaches: <ol> <li>Using the Conventions API</li> <li>Creating a custom IContentApiModelProperty implementation</li> <li>Using the Graph Source SDK</li> </ol> Each method offers a different level of control, flexibility, and effort. Let's dive in. <h2 class="flex scroll-m-28 flex-row items-center gap-2">1. Using the Conventions API</h2> The first and most straightforward method for influencing how your data is indexed in Optimizely Graph is through the Conventions API. This API allows developers to modify or extend how CMS content is represented when it's sent to the indexing pipeline. In other words, before your content gets published to Graph, the Conventions API gives you a hook to reshape or enrich the data. <h3 class="flex scroll-m-28 flex-row items-center gap-2">When to use it</h3> If you only need to: <ul> <li>Exclude specific properties or content types,</li> <li>Include some custom fields,</li> <li>Add some lightweight metadata derived from existing content properties</li> </ul> …then the Conventions API is your best friend. <h3 class="flex scroll-m-28 flex-row items-center gap-2">Example:</h3> Let's say you have a LandingPage and InternalSettingsPage content types: <pre class="language-csharp"><code>// InternalSettingsPage.cs [ContentType(DisplayName = "Internal Settings Page")] public class InternalSettingsPage : SitePageData { [Display( Name = "Some Internal Setting", Description = "A confidential value / setting that should not be published in Graph")] public virtual string? SomeInternalSetting { get; set; } }</code></pre> <pre class="language-csharp"><code>// LandingPage.cs using EPiServer.Core; using EPiServer.DataAnnotations; using System.ComponentModel.DataAnnotations; [ContentType(DisplayName = "Landing Page")] public class LandingPage : SitePageData { [Display( Name = "Secret Property", Description = "A confidential value not published in Graph")] public virtual string? SecretProperty { get; set; } [Display( Name = "Title Prefix", Description = "Prefix for the page title")] public virtual string? TitlePrefix { get; set; } [Display( Name = "Title", Description = "The main page title")] public virtual string? Title { get; set; } public virtual string PageTitle() { return TitlePrefix + " " + Title; } }</code></pre> For these content types you want to: <ul> <li>Exclude InternalSettingsPage content type from being indexed to Graph</li> <li>Exclude the SecretProperty to prevent it from leaking into Graph, and</li> <li>Include custom PageTitle property (being a mix of TitlePrefix and Title properties) in the Graph index</li> </ul> You can do it with a simple convention registration: <pre class="language-csharp"><code>// GraphConventions.cs using EPiServer.Framework; using EPiServer.Framework.Initialization; using EPiServer.ServiceLocation; using Optimizely.ContentGraph.Cms.NetCore.ConventionsApi; [ModuleDependency(typeof(EPiServer.Web.InitializationModule))] public class GraphConventions : IInitializableModule { public void Initialize(InitializationEngine context) { var conventionRepository = context.Locate.Advanced.GetInstance<ConventionRepository>(); conventionRepository.ExcludeContentType<InternalSettingsPage>(); conventionRepository.ForInstancesOf<LandingPage>() .ExcludeField(x => x.SecretProperty); conventionRepository.ForInstancesOf<LandingPage>() .IncludeField(x => x.PageTitle()); } public void Uninitialize(InitializationEngine context) { } }</code></pre> Once this convention is registered, Optimizely will skip excluded content types and apply defined adjustments whenever a <code>LandingPage</code> is serialized for indexing in Graph. <h2 class="flex scroll-m-28 flex-row items-center gap-2">2. Creating a Custom IContentApiModelProperty</h2> Sometimes conventions alone aren't enough. Maybe you want to inject dynamic data that doesn't exist in CMS at all — data coming from another service, or a calculated value that depends on runtime conditions. That's when IContentApiModelProperty comes into play. <h3 class="flex scroll-m-28 flex-row items-center gap-2">What it does</h3> IContentApiModelProperty allows you to define a new property that will be available for all content items (or selected ones) when indexed in Optimizely Graph. You can think of it as a plug-in point for adding custom, computed, or external data to the Graph model. <h3 class="flex scroll-m-28 flex-row items-center gap-2">Example: Adding a custom property</h3> Here's a simple implementation: <pre class="language-csharp"><code>using Optimizely.ContentGraph.Cms.Core.ContentApiModelProperties; public sealed class CustomApiModelProperty : IContentApiModelProperty { private readonly IContentLoader _contentLoader; public CustomApiModelProperty(IContentLoader contentLoader) { _contentLoader = contentLoader; } public string Name => "CustomPropertyName"; public object GetValue(ContentApiModel contentApiModel) { // Example: Load the content and derive a value dynamically if (_contentLoader.TryGet( new ContentReference(contentApiModel.ContentLink.Id ?? 0), out SitePageData page)) { return $"calculated-value-for-{page.Name}"; } return null; } }</code></pre> When this property is registered, every content item sent to Optimizely Graph will include an additional field called CustomPropertyName, with whatever value you return from GetValue(). For example, the Graph output might look like this: <pre class="language-javascript"><code>{ "name": "About Us", "customPropertyName": "calculated-value-for-About Us" }</code></pre> <h3 class="flex scroll-m-28 flex-row items-center gap-2">Practical uses</h3> <ul> <li>Injecting content from external APIs (for example, pulling stock data for product pages)</li> <li>Calculating derived values (e.g., reading time, rating averages)</li> <li>Adding environment or contextual metadata</li> </ul> <h2 class="flex scroll-m-28 flex-row items-center gap-2">3. Using the Graph Source SDK</h2> The last approach is the most flexible — and the most decoupled from CMS. If you have data completely external to the CMS (e.g., from a CRM, ERP, or a custom database), you can use the Optimizely Graph Source SDK to push it directly into Graph. The SDK gives you full control over what and how you publish to Optimizely Graph, allowing you to create custom schemas and populate data manually. <h3 class="flex scroll-m-28 flex-row items-center gap-2">When to use it</h3> Use the SDK when: <ul> <li>You need to index non-CMS data (e.g., product catalogs, events, user profiles)</li> <li>You want to synchronize third-party data sources with Graph</li> <li>You're building a headless architecture where CMS is just one of multiple content sources</li> </ul> <h3 class="flex scroll-m-28 flex-row items-center gap-2">Example: Pushing external data</h3> Here's a simplified example based on the <a href="https://github.com/episerver/graph-source-sdk">Graph Source SDK on GitHub</a>: <pre class="language-csharp"><code>using Optimizely.Graph.Source.Sdk; using Optimizely.Graph.Source.Sdk.SourceConfiguration; public class ExternalProduct { public string? Id { get; set; } public string? Name { get; set; } public double Price { get; set; } } // Initialize the GraphSourceClient by calling the Create method var source = "custom-source"; var appKey = "your-app-key"; var secret = "your-secret"; // Initialize the GraphSourceClient by calling the Create method var client = GraphSourceClient.Create(new Uri("https://cg.optimizely.com"), source, appKey, secret); // Add a language preference client.AddLanguage("en"); // Configure content type for ExternalProduct client.ConfigureContentType<ExternalProduct>() .Field(x => x.Id, IndexingType.Searchable) .Field(x => x.Name, IndexingType.Searchable) .Field(x => x.Price, IndexingType.Queryable); // Save content types to Optimizely Graph client.SaveTypesAsync(); // Instantiate and assign values for ExternalProduct var product = new ExternalProduct { Id = "SKU-001", Name = "Custom Running Shoes", Price = 129.99, }; // Use the client to sync the product client.SaveContentAsync(generateId: (x) => x.Id, "en", product);</code></pre> This code defines a custom schema (ExternalProduct) and publishes it to Optimizely Graph. Once indexed, you can query your data directly through GraphQL — just like CMS content. Important note about Optimizely Graph sources: In the code above, we specified the source as custom-source, but you may choose any name to logically separate your data sources. Each source acts as its own container in Optimizely Graph. By default, CMS content is stored in the default source. If you were to use default as the source when pushing custom types, you risk overwriting your entire Graph schema for that source. This is because calling client.SaveTypesAsync() replaces all content types in the target source with only those specified by ConfigureContentType. To avoid disrupting your CMS data and schema, always register external data under a separate source name (such as custom-source). This keeps your external types isolated and safe from unintended changes. <h3 class="flex scroll-m-28 flex-row items-center gap-2">Example query</h3> <pre class="language-javascript"><code>query CustomQuery { ExternalProduct { items { Id Name Price } } }</code></pre> And you'll get: <pre class="language-javascript"><code>{ "data": { "ExternalProduct": { "items": [ { "Id": "SKU-001", "Name": "Custom Running Shoes", "Price": 129.99 } ] } }, "extensions": { "correlationId": "998b0a360df95906", "cost": 23, "costSummary": [ "ExternalProduct(23) = limit(20) + 3*fields(1)" ] } }</code></pre> <h3 class="flex scroll-m-28 flex-row items-center gap-2">Key takeaway</h3> Use the Graph Source SDK when: <ul> <li>Your data lives outside CMS,</li> <li>You want total control over schemas,</li> <li>You're integrating Graph as part of a larger headless ecosystem.</li> </ul> It's the most advanced option — but it also opens up the most possibilities. <h2 class="flex scroll-m-28 flex-row items-center gap-2">Wrapping Up</h2> In a headless setup, Optimizely Graph becomes much more than a content delivery layer. It can act as a centralized data hub — combining CMS content, computed properties, and external datasets under one unified GraphQL API. To recap: <div class="relative overflow-auto prose-no-margin my-6"> <table> <thead> <tr> <th>Approach</th> <th>Best for</th> <th>Level of Effort</th> <th>Notes</th> </tr> </thead> <tbody> <tr> <td>Conventions API</td> <td>Shaping existing CMS data</td> <td>🟢 Low</td> <td>Ideal for renaming, excluding, or slightly enriching data</td> </tr> <tr> <td>IContentApiModelProperty</td> <td>Injecting dynamic or computed data</td> <td>🟠 Medium</td> <td>Great for adding calculated or external fields</td> </tr> <tr> <td>Graph Source SDK</td> <td>Indexing non-CMS data sources</td> <td>🔴 High</td> <td>Full control over schema and indexing</td> </tr> </tbody> </table> </div>   Choosing the right approach depends on your architectural goals — and how “headless” you really want to go. In most projects, a combination works best: <ul> <li>Use Conventions for quick tweaks,</li> <li>Add custom properties for dynamic logic, and</li> <li>Extend with the SDK when you need full control.</li> </ul> That's it for this installment of Going Headless! In the next part, we'll look at how to query your combined datasets efficiently — and how to design your schema for real-world performance. <h3 class="flex scroll-m-28 flex-row items-center gap-2">Further Reading</h3> <ul> <li><a href="https://docs.developers.optimizely.com/graph/docs">Optimizely Graph Documentation</a></li> <li><a href="https://docs.developers.optimizely.com/content-management-system/docs/conventions-api">Conventions API Reference</a></li> <li><a href="https://github.com/episerver/graph-source-sdk">Graph Source SDK on GitHub</a></li> <li><a href="/link/e41f24d11ff7488db0b8ccc26b9711a7.aspx">Going Headless: Making the Right Architectural Choices</a></li> <li><a href="/link/c4887f08a93144b19377f27068985f71.aspx">Going Headless: Optimizely Graph vs Content Delivery API</a></li> </ul>2025-11-03T10:23:28.0000000Z

Blog post

Going Headless - 3 Ways to Store Custom Data in Optimizely GraphThree different approaches to storing custom data in Optimizely Graph.2025-11-03T00:00:00.0000000Z

Blog post

Going Headless: Making the Right Architectural ChoicesEarlier this year, I began a series of articles about headless architecture: <ul> <li><a href="/link/c4887f08a93144b19377f27068985f71.aspx">Going Headless: Optimizely Graph vs Content Delivery API</a></li> <li><a href="/link/425ad6b768e94410ab706643559c4f96.aspx">Going Headless: On-Page Editing with Optimizely Graph and Next.js</a></li> </ul> Today's post continues that series. Having just completed the launch of a new website built with a headless architecture, I'd like to share key observations, strategic considerations, and my own perspective on the strengths and challenges of the headless model. My goal is to help you make confident, informed choices for your own future project architecture. <h2 class="flex scroll-m-28 flex-row items-center gap-2">What This Article Covers</h2> In today's post, we'll start with the fundamentals: <ul> <li>What “headless” really means in the Optimizely context</li> <li>Why some choose it (and why some shouldn't)</li> <li>Choosing the right architecture for your headless Optimizely setup</li> <li>A high-level architecture overview to ground future discussions</li> </ul> <h2 class="flex scroll-m-28 flex-row items-center gap-2">What “Headless” Means in the Optimizely World</h2> In a headless Optimizely setup, the CMS focuses on storing and structuring content and exposing it via APIs. Whether you use a <a href="/link/c4887f08a93144b19377f27068985f71.aspx">Content Delivery API or Optimizely Graph</a>, the “head” (the UI) is a separate app that fetches the content and renders it. <h2 class="flex scroll-m-28 flex-row items-center gap-2">When Headless Might Not Be the Right Choice</h2> The headless separation lets the front-end team ship without touching the CMS, and enables you to serve multiple channels from a single content source. While this flexibility is appealing, headless isn't always the right fit for every scenario. When headless may not be necessary: <ul> <li>Simple site needs: If you only require a basic site, headless can introduce unnecessary complexity.</li> <li>Limited developer capacity: Headless architectures require a skilled front-end team comfortable with API-driven development.</li> <li>Budget constraints: Having two applications means you need to host two applications. This can impact your infrastructure or require additional licences and potentially higher costs.</li> </ul> Key challenges of going headless: <ul> <li>Routing and URL management: You are responsible for route generation and resolution (slugs, dynamic routes, canonical URLs, redirects, and localization-aware paths). With Optimizely Graph, there's no built-in URL resolver, so you must design and maintain this logic on the front end.</li> <li>On-page editing and preview: Traditional on-page editing from MVC is not available by default. You'll need to implement preview rendering of drafts, signed preview tokens, and live refresh hooks. If editors require a visual page preview, you'll have to build or integrate that experience. As a starting point you can follow my guide - <a href="/link/425ad6b768e94410ab706643559c4f96.aspx">Going Headless: On-Page Editing with Optimizely Graph and Next.js</a></li> <li>CI/CD complexity: Headless usually means separate pipelines for the CMS and front end, so you need to coordinate deployments and keep everything in sync. Additionally, managing schema changes in Optimizely Graph introduces further challenges, as updates must be reflected and tested across both applications.</li> <li>Authentication and authorization: You'll need to handle user logins, editor previews, and protect your APIs. This means managing secrets and reviewing security.</li> </ul> As you can see, adopting a headless approach involves trade-offs and added complexity. Make sure your decision is guided by genuine business requirements, rather than simply following industry trends. <h2 class="flex scroll-m-28 flex-row items-center gap-2">When Headless Is a Way To Go</h2> Opting for a headless architecture can be a game changer for organizations that need agility, omnichannel delivery, and modern development workflows. If your content needs to be reused across multiple front ends—such as websites, mobile apps, IoT devices, or digital kiosks — headless streamlines the process and reduces duplication. It enables independent development and deployment of the frontend and backend, letting teams iterate quickly and select best-in-class technologies for each layer. For companies with demanding editorial workloads, headless can provide enhanced flexibility, customizable authoring experiences, and the ability to scale globally by leveraging CDN-backed static sites or API-first delivery. If you need powerful integrations, advanced personalization, or the latest in frontend performance tooling, headless often opens more doors than traditional approaches. Ultimately, headless is especially valuable when your project requires future-proofing, composability, and the freedom to evolve both your frontend and backend at their own pace. <h2 class="flex scroll-m-28 flex-row items-center gap-2">Choosing the Right Architecture for Your Headless Optimizely</h2> When picking your setup, balance short-term delivery with long-term flexibility. Consider who you're building for, which channels you must support, your team's skills, latency/scale needs, security/compliance, and total cost of ownership. Write these down up front-they'll keep trade-offs honest. <h1 class="flex scroll-m-28 flex-row items-center gap-2">Technical decisions</h1> These days, the variety of tools and architectural options can feel overwhelming, so it's impossible to cover every scenario here. Instead, I'll highlight some key decisions I've faced recently and briefly explain each. Hopefully, these insights will be helpful. <h3 class="flex scroll-m-28 flex-row items-center gap-2">CMS PaaS vs SaaS</h3> PaaS offers greater control over your codebase and infrastructure, but comes with increased operational responsibilities. SaaS minimizes maintenance and accelerates upgrades, though it restricts server-side customization and hosting flexibility. Your choice should depend on your need for custom server logic and regional deployment control. For our project, we selected PaaS to retain full control over our source code and to support future integrations. <h3 class="flex scroll-m-28 flex-row items-center gap-2">Optimizely DXP vs self-hosted</h3> DXP gives you managed hosting, a global CDN, built-in security, and guaranteed SLAs right from the start. So a lot of the heavy lifting is taken care of for you. On the other hand, self-hosting might be the way to go if you have strict data residency requirements or unique networking needs, but just keep in mind that you'll be responsible for monitoring, scaling, patching, and handling any incidents yourself. Be sure to realistically weigh the operational costs of each option before making your choice. <h3 class="flex scroll-m-28 flex-row items-center gap-2">Graph (GraphQL) vs CDA (Content Delivery API)</h3> Optimizely Graph shifts content delivery to a managed service, enabling precise GraphQL queries-ideal for retrieving deeply nested or specific content-and offers advanced search capabilities. In contrast, the Content Delivery API (CDA) is simpler, REST-based, and provides built-in URL resolution, but may require additional effort for complex content structures or scaling needs. For a detailed comparison, see my article: <a href="/link/c4887f08a93144b19377f27068985f71.aspx">Going Headless: Optimizely Graph vs Content Delivery API</a>. For our project, we chosed Optimizely Graph because its data residency met our requirements and it provided greater flexibility for content delivery. <h3 class="flex scroll-m-28 flex-row items-center gap-2">Next.js vs other front-end frameworks</h3> Next.js offers SSR, SSG, and ISR out of the box, making it a strong choice for content-rich sites. Alternatives like React with Vite or Angular are also solid. Choose the framework your team is most comfortable with and that aligns with your hosting environment (Node, Edge, or serverless). For our project, rapid time to market was essential. We selected Next.js together with Vercel for its seamless support of SSR/SSG/ISR, integrated Turbo monorepo tooling, and a deployment workflow that enabled us to iterate quickly, gather feedback, and launch efficiently. If you're using the SaaS version of Optimizely CMS, you may want to explore the newly introduced DXP hosting for front-end applications. Learn more in the official documentation: <a href="https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/host-a-front-end-with-optimizely">https://docs.developers.optimizely.com/content-management-system/v1.0.0-CMS-SaaS/docs/host-a-front-end-with-optimizely</a> <h3 class="flex scroll-m-28 flex-row items-center gap-2">GitHub vs Azure DevOps</h3> Pick the platform your team knows and that fits your cloud targets. GitHub pairs nicely with Actions and Vercel; Azure DevOps integrates tightly with Azure and enterprise governance. Both support trunk-based development, protected branches, and good CI/CD. We chose GitHub because we didn't need the additional features offered by Azure DevOps, and hosting our app in DXP meant Azure integrations were minimal. GitHub's seamless integration with Vercel was also a significant advantage for our workflow. <h3 class="flex scroll-m-28 flex-row items-center gap-2">Opti ID vs other SSO providers</h3> Use Opti ID where it makes sense within the Optimizely ecosystem. For your site/app users and internal editors, standard OpenID Connect/SAML providers (Azure AD, Okta, Auth0, etc.) work well. Confirm MFA, provisioning, and claim mapping early. We selected Opti ID because it met all our requirements and enabled us to implement authentication quickly and efficiently. For more details, refer to the official documentation: <a href="https://support.optimizely.com/hc/en-us/articles/12613241464461-Get-started-with-Opti-ID">https://support.optimizely.com/hc/en-us/articles/12613241464461-Get-started-with-Opti-ID</a> <h3 class="flex scroll-m-28 flex-row items-center gap-2">Common Repository vs Separate Repositories</h3> In a headless setup, the frontend and the CMS/backend are independent. You can keep them in one repository (monorepo) or split them into separate repositories. <ul> <li> Monorepo (one repository): <ul> <li>Pros: single place for code and tooling, atomic changes across front end and CMS, easier end-to-end testing and shared packages</li> <li>Cons: more complex pipelines, risk of unnecessary deploys without proper path filters, larger repo to maintain</li> </ul> </li> <li> Separate repositories: <ul> <li>Pros: clear ownership and access control, simpler pipelines per app, easier to replace one part without touching the other</li> <li>Cons: coordination overhead (shared contracts, schemas, SDK versions), more cross-repo communication</li> </ul> </li> </ul> Opt for a single repository when teams need to collaborate closely, share code, or coordinate changes across frontend and backend. Separate repositories are preferable when independent deployments and isolated responsibilities are a priority. We chose a monorepo approach because our team size makes close collaboration easier, and it gives us greater control and visibility over the entire CI/CD process. <h1 class="flex scroll-m-28 flex-row items-center gap-2">Summary</h1> In summary, successful modern web architecture is about making the right choices for your team, business needs, and long-term maintainability. Each architectural decision, whether it's PaaS vs SaaS, managed services vs custom hosting, or selecting the front-end framework should reflect your unique requirements in performance, scalability, flexibility, and collaboration. By evaluating trade-offs at each level and prioritizing seamless integration, you can build solutions that are robust, adaptable, and future-proof.2025-10-17T07:19:44.0000000Z

Blog post

Going Headless - Making the Right Architectural ChoicesA high-level overview of the architectural decisions made for the new website built with a headless architecture.2025-10-17T00:00:00.0000000Z

Blog post

Going Headless: On-Page Editing with Optimizely Graph and Next.js<div class="prose"> <h2 class="flex scroll-m-28 flex-row items-center gap-2">Introduction</h2> On-page editing is one of the standout features of Optimizely CMS, giving editors the power to update content directly on the site as they see it. But when you move to a headless architecture, bringing that seamless editing experience to your custom frontend can seem daunting. The good news? It's absolutely possible and not as complicated as you might think! In this article, I'll walk you through how to enable on-page editing in your own solution using Next.js, so your editors can enjoy the best of both worlds: modern headless flexibility and intuitive in-context editing. <h2 class="flex scroll-m-28 flex-row items-center gap-2">How does On-Page Editing work in a headless setup?</h2> <img src="/link/13c2a20625f14bc7ad8c5a88898bfd37.aspx" width="896" height="634" /> Here's how the process typically works: <ul> <li>Optimizely CMS loads your frontend site inside an iframe.</li> <li>Your frontend detects that it's running within the CMS iframe and automatically switches to draft mode, displaying preview versions of pages or blocks.</li> </ul> By including the communicationinjector.js script (provided by your Optimizely CMS app), your frontend can listen for and respond to events triggered from the CMS editor. <h2 class="flex scroll-m-28 flex-row items-center gap-2">Step 1: Display the frontend in an iframe</h2> There are a few things we need to do to display our frontend app in an iframe inside the CMS. First things first-tell Optimizely Graph to include all draft content by adding "AllowSyncDraftContent": true. When enabled, Graph indexes draft content and makes it available to the frontend. Let's also add Headless:FrontEndUri so we can configure CORS for the frontend site. <pre class="language-csharp"><code>//appsettings.json { "Optimizely": { "ContentGraph": { "GatewayAddress": "https://cg.optimizely.com", "AppKey": "YOUR_APP_KEY", "Secret": "YOUR_SECRET_KEY", "SingleKey": "YOUR_SINGLE_KEY", "AllowSyncDraftContent": true } }, "Headless": { "FrontEndUri": "https://localhost:3000" } }</code></pre> To keep things clean, add an extension we'll use in Startup.cs <pre class="language-csharp"><code>// HeadlessExtensions.cs using EPiServer.ContentApi.Core.DependencyInjection; using EPiServer.Web; public static class HeadlessExtensions { public static IServiceCollection AddHeadlessOnPageEditing(this IServiceCollection serviceCollection) { serviceCollection // Configure our CMS to use External Templates and to OptimizeForDelivery. // This will allow the Edit UI to load the decoupled delivery site into On Page Edit. // It will also instruct the overlay's bounding boxes to include floating instead of inline editors. // This is required to avoid cross-origin issues between the domain of the iframe and of the CMS itself. .ConfigureForExternalTemplates() .Configure<ExternalApplicationOptions>(options => options.OptimizeForDelivery = true) return serviceCollection; } public static IApplicationBuilder AddCorsForFrontendApp(this IApplicationBuilder app, string? frontendUri) { if (!string.IsNullOrWhiteSpace(frontendUri)) { app.UseCors(b => b .WithOrigins($"{frontendUri}", "*") .WithExposedContentDeliveryApiHeaders() .WithHeaders("Authorization") .AllowAnyMethod() .AllowCredentials()); } return app; } public static IApplicationBuilder AddRedirectToCms(this IApplicationBuilder app) { // Since it's a headless setup we can redirect user from "/" directly to CMS app.UseStatusCodePages(context => { if (context.HttpContext.Response.HasStarted == false && context.HttpContext.Response.StatusCode == StatusCodes.Status404NotFound && context.HttpContext.Request.Path == "/") { context.HttpContext.Response.Redirect("/episerver/cms"); // or /ui/cms if you use OptiID or have changed path to your CMS //context.HttpContext.Response.Redirect("/ui/cms") } return Task.CompletedTask; }); return app; } }</code></pre> Now use this extension in Startup.cs <pre class="language-csharp"><code>// Startup.cs public class Startup { private readonly IWebHostEnvironment _webHostingEnvironment; private readonly IConfiguration _configuration; private readonly string? _frontendUri; public Startup(IWebHostEnvironment webHostingEnvironment, IConfiguration configuration) { // ... _frontendUri = _configuration.GetValue<string>("Headless:FrontEndUri"); } public void ConfigureServices(IServiceCollection services) { // ... services.AddHeadlessOnPageEditing(); } public void Configure(IApplicationBuilder app, IWebHostEnvironment env) { // ... app.AddCorsForFrontendApp(_frontendUri); app.AddRedirectToCms(); } }</code></pre> Neat and clean. Next, enable the frontend to be loaded in an iframe. Add an environment variable: <pre class="language-csharp"><code>// .env.local NEXT_PUBLIC_CMS_URL="https://localhost:5096" </code></pre> and use it in the Next.js config: <pre class="language-javascript"><code>// next.config.mjs async headers() { return [ { source: '/:path*', headers: [ { key: 'X-Frame-Options', value: 'SAMEORIGIN' }, { key: 'Content-Security-Policy', value: `frame-ancestors 'self' ${process.env.NEXT_PUBLIC_CMS_URL || 'localhost:5096'}`, }, ], }, ] },</code></pre> Finally, go to "Manage Websites" and define hosts for both the CMS and the frontend apps. Set this up correctly or the CMS won't be able to display previews from a different host. In example below: <ul> <li>CMS app: https://localhost:5096/</li> <li>Frontend client: https://localhost:3000/</li> </ul> <div class="flex gap-2 my-4 rounded-xl border bg-fd-card p-3 ps-1 text-sm text-fd-card-foreground shadow-md"> <div class="flex flex-col gap-2 min-w-0 flex-1"> <div class="text-fd-muted-foreground prose-no-margin empty:hidden"> Run both CMS and frontend on the same protocol, preferably HTTPS. Otherwise the CMS won't load the iframe. </div> </div> </div> <img src="/link/474260c1ab4c44819d3edcc71b1c8ea3.aspx" width="1019" height="1030" /> Now when you edit a page, the CMS should load the frontend, likely showing a 404. That's because Optimizely opens the iframe with a predefined URL that we need to handle. <h2 class="flex scroll-m-28 flex-row items-center gap-2">Step 2: Draft mode and page preview</h2> To make On-Page Editing work in our Next.js app we need to use draft mode. Draft Mode allows you to preview draft content from your headless CMS in your Next.js application. This is useful for static pages that are generated at build time as it allows you to switch to dynamic rendering and see the draft changes without having to rebuild your entire site. When the CMS loads a preview in an iframe it will hit one of two URLs: <ul> <li>https://localhost:3000/episerver/CMS/Content/en/,,5_8?epieditmode=true for pages</li> <li>https://localhost:3000/episerver/CMS/contentassets/en/77364cdc2802407b8b8cae45b65bc16e/,,7_10?epieditmode=true for blocks</li> </ul> These URLs contain the following information: <ul> <li>en - content locale</li> <li>5_8 or 7_10 - ID (5 for page, 7 for block) and workId (8 for page, 10 for block). id identifies the content; workId identifies the version.</li> <li>epieditmode - distinguishes page preview (epieditmode=false) from On-Page Editing (epieditmode=true).</li> </ul> Knowing these URLs, set up redirects in your Next.js app: <pre class="language-javascript"><code>// next.config.mjs async redirects() { return [ { source: '/episerver/CMS/Content/:slug*', destination: '/api/draft/:slug*', permanent: false, } ] },</code></pre> <div class="flex gap-2 my-4 rounded-xl border bg-fd-card p-3 ps-1 text-sm text-fd-card-foreground shadow-md"> <div class="flex flex-col gap-2 min-w-0 flex-1"> <div class="text-fd-muted-foreground prose-no-margin empty:hidden"> If you're using OptiID or changed the CMS URL, you might need to replace episerver with ui or another prefix. </div> </div> </div> Now all requests to /episerver/CMS/Content/* and /episerver/CMS/contentassets/* will be redirected to our draft API route. Here we need to: <ul> <li>Enable draft mode by calling (await draftMode()).enable(). This allows bypassing static generation and rendering on-demand at request time</li> <li>Extract parameters from URL</li> <li>Redirect to a draft (for page or block) and pass extracted parameters</li> </ul> <pre class="language-javascript"><code>// src/app/api/draft/[...slug]/route.ts" import { redirect, notFound } from 'next/navigation'; import { NextRequest } from 'next/server'; import { draftMode } from 'next/headers' export async function GET(request: NextRequest) { const url = new URL(request.url); const { searchParams, pathname } = url; // There are 2 different type of URLs to handle here... // For Page: // /api/draft/en/,,5_8?epieditmode=true // For Blocks: // /api/draft/contentassets/en/77364cdc2802407b8b8cae45b65bc16e/,,7_10?epieditmode=true // To get the value of a search param, use .get('<paramName>') const epiEditMode = searchParams.get('epieditmode'); // Remove leading '/api/draft/' from pathname let path = pathname.replace(/^\/api\/draft\//, ''); // Assess type of content const isBlock = path.startsWith('contentassets'); path = isBlock ? path.replace("contentassets/", "") : path; // Extract locale + ids (Optimizely-specific pattern: /en/,,5_8) const segments = path.split("/"); const locale = segments[0] || "en"; const idsPart = segments[segments.length - 1] || ""; const [, ids = ""] = idsPart.split(",,"); const [id = "0", workId = "0"] = ids.split("_"); // Validate all required fields if (!locale || !id || !workId || !epiEditMode) { return notFound(); } // Enable draft mode (await draftMode()).enable() const newSearchParams = new URLSearchParams({ locale, id, workId, epiEditMode, }); const newUrl = isBlock ? `/draft/block?${newSearchParams.toString()}` : `/draft?${newSearchParams.toString()}`; redirect(`${newUrl}`); }</code></pre> <h2>Step 3: Include the communicationinjector.js script</h2> To enable seamless communication between your draft site and the CMS for on-page editing, you must add the communicationinjector.js script to your draft layout. This script, served from your CMS instance, is required for listening to content save events and enabling real-time editing capabilities. Include it in your layout file: <pre class="language-javascript"><code><Script src={`${process.env.NEXT_PUBLIC_CMS_URL}/util/javascript/communicationinjector.js`} /></code></pre> <h2>Step 4: Display the draft for a page.</h2> A key aspect is the data-epi-edit attribute, which tells Optimizely which field is editable on the page. In the example above, we set its value to "title", matching the property name in the CMS. <pre class="language-javascript"><code>// src/app/draft/page.tsx import { renderBlocks } from '@repo/helpers'; import { draftMode } from 'next/headers'; import { notFound } from 'next/navigation'; import * as blockComponents from '~/blocks'; import { getPageContentById } from '~/cms/helpers'; import OnPageEdit from '~/components/draft/OnPageEdit'; import type { AllBlocks } from '~/types'; import type { OptiPreviewPageProps } from '~/types-legacy'; // Ensure this page is always rendered on-demand and never statically cached export const revalidate = 0; export const dynamic = 'force-dynamic'; export default async function PreviewPage({ searchParams, }: OptiPreviewPageProps) { const { isEnabled: isDraftModeEnabled } = await draftMode(); if (!isDraftModeEnabled) { return notFound(); } // Fetch the page content in draft mode using the provided search parameters const page = await getPageContentById({ id: searchParams.id, workId: searchParams.workId, locale: searchParams.locale, preview: true, }); if (!page) return notFound(); return ( <> <OnPageEdit currentRoute={`/draft?${new URLSearchParams(searchParams).toString()}`} workId={searchParams.workId} /> {/* Render the page title with Optimizely's on-page editing attribute */} {page.title && <h2 data-epi-edit="title">{page.title}</h2>} <div data-epi-edit="mainContentArea" is-on-page-editing-block-container="true"> {renderBlocks<AllBlocks>(page.blocks, blockComponents, { showDataOnMissingBlock: true, arbitraryData: { searchParams }, weave: ['backgroundColor'], })} </div> </> ); }</code></pre> Ensure that your getPageContentById function correctly handles the preview flag. When preview is true, you must use a different authentication method for Optimizely Graph to access draft content. Without this, fetching draft content will not work. For details on authenticating with Optimizely Graph, see the <a href="https://docs.developers.optimizely.com/platform-optimizely/docs/basic-auth">official documentation</a>. This page layout uses the OnPageEdit component - the cherry on top that handles communication with the CMS. <pre class="language-javascript"><code>// src/components/draft/OnPageEdit.tsx 'use client'; import { useRouter } from 'next/navigation'; import { useEffect, useRef } from 'react'; interface EpiAPI { subscribe: (event: string, handler: (event: any) => void) => void; unsubscribe?: (event: string, handler: (event: any) => void) => void; } interface WindowWithEpi extends Window { epi?: EpiAPI; } interface ContentSavedProperty { name: string; value: string; successful: boolean; validationErrors: string; } interface ContentSavedEventArgs { contentLink: string; previewUrl: string; editUrl: string; properties: Array<ContentSavedProperty>; } interface OnPageEditProps { workId: string; currentRoute: string; } // This component listens for changes made in the Optimizely CMS editor and updates the preview of a page or block accordingly. // When a change is made in the CMS, Optimizely emits a "contentSaved" event via the communicationinjector.js script. // The event includes a list of updated properties. For significant changes, Optimizely may increment the workId of the edited content, // returning the new workId as part of the content URL in the "contentSaved" event. const OnPageEdit = ({ workId, currentRoute, }: OnPageEditProps) => { const router = useRouter(); // Listen for "contentSaved" events from the CMS editor, which may fire multiple times per change. // To avoid processing duplicate events, keep track of the last handled event and only process new ones. const prevMessageRef = useRef<ContentSavedEventArgs | null>(null); useEffect(() => { // Handle content saved events from Optimizely CMS const handleContentSaved = (event: any) => { const message = event as ContentSavedEventArgs; // Check if the event is a duplicate const prevMessage = prevMessageRef.current; if ( prevMessage && JSON.stringify(prevMessage) === JSON.stringify(message) ) { // Skip the event return; } prevMessageRef.current = message; // Since Optimizely Graph is external service, it may take some time to propagate the changes. // That's why simple "refresh" is not sufficient to provide seamless editing experience. // We need to look inside "contentSaved" event and update the DOM with the new content. message.properties?.forEach((prop) => { if (!prop.successful) return; // Find matching elements in the DOM const elements = document.querySelectorAll<HTMLElement>( `[data-epi-edit="${prop.name}"]`, ); elements.forEach((el) => { // Skip elements inside content areas that are marked as "is-on-page-editing-block-container" if (el.closest('[is-on-page-editing-block-container]')) { return; } // Replace text content el.textContent = prop.value; }); }); // When a major content change occurs, Optimizely increments the workId and provides a new draft URL. // If the workId has changed, update the URL to fetch the latest draft content from Graph. // Extract the new workId from the contentLink (format: "id_workId"). const [, newWorkId] = message?.contentLink?.split('_'); if (newWorkId && newWorkId !== workId) { const newUrl = currentRoute?.replace( `workId=${workId}`, `workId=${newWorkId}`, ); router.push(newUrl); } }; // ----------------------------------------------- // Subscribe for Optimizely CMS events // ----------------------------------------------- // Next.js pages are first server-rendered and then hydrated on the client. // window.epi (Optimizely API) may not exist immediately on hydration, // so we poll every 500ms until it becomes available. let interval: NodeJS.Timeout; const trySubscribe = () => { const win = window as WindowWithEpi; if (win.epi) { win.epi.subscribe('contentSaved', handleContentSaved); clearInterval(interval); // Stop polling once subscribed } }; interval = setInterval(trySubscribe, 500); trySubscribe(); // try immediately too // ----------------------------------------------- // Cleanup // ----------------------------------------------- // Avoid duplicate subscriptions or memory leaks return () => { clearInterval(interval); const win = window as WindowWithEpi; if (win.epi) { win.epi.unsubscribe?.('contentSaved', handleContentSaved); } }; }, [currentRoute, router, workId]); return null; }; export default OnPageEdit;</code></pre> <h2>Summary</h2> I hope this article has helped clarify how to implement on-page editing in your own headless Next.js solution. With these steps, you should be well-equipped to bring a seamless editing experience to your editors, combining the flexibility of headless architecture with the intuitive in-context editing of Optimizely CMS. Thanks for following along - happy building! </div>2025-09-10T09:52:20.0000000Z

Blog post

Going Headless - On-Page Editing with Optimizely Graph and Next.jsHow to enable on-page editing in your own solution using Next.js.2025-09-10T00:00:00.0000000Z

Blog post

Common Pitfalls with Search in Optimizely Graph - and How to Avoid ThemOptimizely Graph offers powerful, flexible search capabilities out of the box, making it a popular choice for headless implementations. However, like any robust system, it comes with nuances that can trip you up if you’re not careful. In this post, I’ll try to cover common pitfalls developers may encounter when working with search in Optimizely Graph, especially around content duplication, unintentional exposure, and content provider handling - and show you how to avoid them. <h2>Duplicate Content in Search Results</h2> One of the most frustrating issues is seeing the same content item indexed multiple times or search results returning unexpected duplicates. <h3>Incorrect Authentication Mode</h3> Optimizely Graph exposes not only the published versions of your content but also includes drafts and other unpublished versions. This is particularly useful for building custom on-page editing experiences in headless setups. However, it also introduces a potential risk: unpublished content may unintentionally appear in search results if access controls are not correctly configured. <h4>Recommended Solution</h4> To mitigate this, it's crucial to separate authentication modes between editing and search functionalities: <ul> <li> On-page editing should use authenticated access to retrieve drafts and work-in-progress content. </li> <li> Public search should be limited strictly to published content and operate under a separate, read-only context. </li> </ul> Reusing tokens or authentication flows between these use cases should be strictly avoided. This may also be a potential security concern if not handled properly - but that’s a topic worthy of a separate article. For implementation guidance and best practices, refer to the official documentation: <a href="https://docs.developers.optimizely.com/platform-optimizely/docs/authentication">Authentication – Optimizely Graph</a> <h3>Shortcut Pages Misindexed</h3> In Optimizely CMS, pages using Shortcuts (e.g., “Fetch content from another page”, see<a href="https://support.optimizely.com/hc/en-us/articles/4413192312077-All-Properties-editing-view#h_01HBH992DX0NCZW2W8SF86X50Z"> documentation</a>) are by default indexed as standalone pages, even though they point to other content. This behavior can result in unexpected duplicate entries in your search results, which may negatively affect content relevance and SEO. <h4>Recommended Solution</h4> To prevent this, it's important to filter out shortcut pages at the query level during indexing or search execution. A more robust and maintainable solution is to: <ol> <li> Introduce a custom property like ExcludeFromSearch (boolean). </li> <li> Automatically set this property to true for shortcut pages (e.g., in content events). </li> <li> Respect this property in your search queries by excluding any pages where ExcludeFromSearch == true. </li> </ol> This approach not only handles shortcut pages gracefully but also gives editors fine-grained control over which pages should be searchable. <h2>Exposing Technical Content That Shouldn't Be Indexed</h2> It’s not uncommon for non-public content - such as settings pages, container pages, or system-level content-to inadvertently appear in Graph search results. These items were never intended to be publicly accessible and can clutter search experiences or expose internal information. <h4>Common Causes</h4> <ul> <li> Missing exclusion flags on special or restricted content. </li> <li> Lack of visibility review during the Graph schema setup. </li> <li> Overly broad queries that don’t filter by content purpose or type. </li> </ul> <h4>How to Prevent It</h4> Use Graph filters to explicitly exclude: <ul> <li> Content in designated folders (e.g. /settings, /utility) </li> <li> Content with a flag like ExcludeFromSearch = true </li> <li> Specific content types not meant for search (e.g. SiteSettingsPage, RedirectPage) </li> </ul> <h4>Best Practice</h4> Implement an ExcludeFromSearch property on all content types. This offers low coupling between search logic and CMS structure, and allows editors or developers to easily manage visibility without tightly binding filtering rules to folder paths or content type checks. <h2>Multilingual Content in Optimizely Graph</h2> In most cases, our content exists in multiple languages. However, a basic language filter in a Graph query may unintentionally exclude content that lacks a translation in the currently selected site language. <h4>Example Scenario:</h4> <ul> <li> A user is browsing the site in German ("de"). </li> <li> The CMS has a fallback language set to English ("en"). </li> <li> Some product pages have not yet been translated into German. </li> <li> A basic Graph filter like Language: { Name: { eq: "de" } } will exclude these untranslated pages, even if fields like the product name are language-agnostic and would otherwise match the search criteria. </li> </ul> <h4>Why This Matters:</h4> Depending on your business needs, showing fallback content might be acceptable or preferred. However, even if you choose not to display it, it’s important to make that decision consciously, not by default behavior. <h4>Recommended Approach:</h4> To support fallback languages in search results, leverage the following Graph fields: <ul> <li> MasterLanguage: Indicates the original language of the content. </li> <li> ExistingLanguages: Lists all languages the content has been translated into. </li> </ul> By using these properties, you can intelligently include fallback content in queries-ensuring a better user experience while respecting localization strategy. <h2>Poor Relevance and Ranking in Search Results</h2> Even with a clean index and a well-designed Graph schema, search results can appear noisy, irrelevant, or misleading if queries aren’t thoughtfully constructed. Common issues like missing field boosting, unfiltered related content, and generic query logic can cause even high-quality content to be buried beneath less relevant matches. <h3>Missing field boosting</h3> By default, all fields are treated equally in Optimizely Graph unless explicitly boosted. This often leads to situations where low-priority fields (e.g., descriptions) match as strongly as high-priority ones (e.g., titles or product names). <h4>Recommendation:</h4> Use field-level boosting to give higher weight to meaningful fields like title, name, or tags. Learn more:<a href="https://docs.developers.optimizely.com/platform-optimizely/docs/boosting"> Boosting in Optimizely Graph</a> <h3>Unintended indexing of related content</h3> Product pages or articles often embed related content (e.g., "Related Products" blocks or references). If this content is indexed directly with the main page, it can bleed into the searchable content of the parent - leading to false positives, confusing matches, and degraded search relevance. <h4>Example:</h4> A product page for a wireless mouse might appear in search results for a mechanical keyboard if a related keyboard product is embedded and indexed as part of the same content. <h4>Recommendation:</h4> Ensure related items are either: <ul> <li> Excluded from the index, or </li> <li> Indexed separately and referenced cleanly, rather than merged into the searchable body of the main item. </li> </ul> <h2>Access-Controlled Content Leaking into Public Search</h2> In many CMS implementations, certain content such as gated resources, subscriber-only pages, or internal documentation should only be accessible to specific user groups. A critical security risk occurs when this restricted content unintentionally appears in public search results, exposing sensitive or paid information to unauthorized users. <h4>Common Cause:</h4> <ul> <li> Incorrect authentication mode used when querying Optimizely Graph, resulting in unrestricted access to protected content. </li> </ul> <h4>How to Prevent It:</h4> To ensure proper access control: <ul> <li> When authenticating to Optimizely Graph, always include the current user context and their roles/permissions. </li> <li> Avoid using system-wide tokens or anonymous access for features that should reflect user-level content restrictions. </li> </ul> Optimizely Graph enforces access control only when explicitly requested via authenticated queries. If omitted, all content-including restricted items-may be returned. <a href="https://docs.developers.optimizely.com/platform-optimizely/docs/basic-auth-from-backend#retrieve-restricted-content">How to retrieve restricted content securely (Optimizely Docs)</a> <h2>Final Thoughts</h2> Optimizely Graph is a powerful tool but like any flexible system, it needs intentional setup and governance to avoid messy search results and content exposure issues. By being aware of the common pitfalls and applying proactive filters, schema hygiene, and provider discipline, you’ll set yourself (and your editors!) up for a clean, accurate, and efficient search experience. Have you run into a tricky Graph issue in production? Let me know - always keen to learn how others are solving these challenges.  2025-06-18T14:16:05.0000000Z

Blog post

Common Pitfalls with Search in Optimizely Graph - and How to Avoid ThemCommon pitfalls developers encounter when working with search in Optimizely Graph and how to avoid them.2025-06-18T00:00:00.0000000Z

Blog post

Going Headless: Optimizely Graph vs Content Delivery APIAs the demand for flexible, multi-channel digital experiences grows, more development teams are turning to headless CMS architectures to future-proof their solutions. Optimizely offers two primary options for headless content delivery: the Content Delivery API (CDA) and the newer Optimizely Graph. But which one should you choose - and why? I recently faced this exact question while starting a greenfield project with a headless approach. During my research, I noticed that most resources focused deeply on either CDA or Graph individually, but very few compared the two in a practical, side-by-side way. In this article, I’ll share what I learned - highlighting the key differences in performance, scalability, routing, search, and more. If you're planning to build a headless or hybrid app with Optimizely CMS and you're still unsure which path to take, this guide is for you. <h3>What Does “Headless” mean and why is it such a hot topic recently?</h3> Before we dive in, let’s quickly define “headless” and clarify what the fuss is all about! In a non-headless CMS, templates, rendering logic, and UI all live in one application: <img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcbNPCzRCnpcL6yVMwQuMvnr8Z-aM3ZH8JVkHDTwt_QghHJiNn2WY1HbRVTJbzr-AWQ3wuUQpYSWvxrLO1cdrtXjdYZ89YSaVDxMxPjoDKZbfIndtNysR6N6q0FPtKIRrJVp4quEw?key=3mOZlVv2ZwJhbbBj73lCAg" width="602" height="281" /> In more complex projects, this approach may introduce a high degree of coupling between the back-end and front-end layers, potentially reducing flexibility. In a headless CMS, the front-end is handled by a separate application. Content is created and stored in the backend but delivered through APIs: <img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXfeR8j6LwckEhi8lrAw5ONIl3hWKSk7LcAnj63lbaXFatvyU0DWtrQ2m_gA9Ni1nv4i5LL494kzrG4gh5Qi7OF1fp5zRY74irCtQJUJq9qbnj8KiJhbhjAkvHN9g10FMqmtjEdr0Q?key=3mOZlVv2ZwJhbbBj73lCAg" width="602" height="476" /> This gives us many advantages that we can utilize to develop more scalable and resilient solutions: <ul> <li> Front-End Flexibility: Use any technology (React, Vue, Next.js, etc.) to build modern, fast, and dynamic user experiences. </li> <li> Omnichannel Delivery: Reuse the same content across websites, mobile apps, kiosks, smart devices, and more. </li> <li> Scalability & Performance: Decoupling content delivery from the CMS backend allows for independent scaling and optimized performance. </li> <li> Faster Development Cycles: Backend and frontend teams can work in parallel and deploy changes separately accelerating time-to-market. </li> <li> Future-Proof Architecture: Easier to swap out or upgrade parts of your stack without replatforming the entire system. </li> </ul> But there’s always a second side of a coin. While going “headless” gives us a great flexibility it also introduces new challenges - especially around content delivery, routing, and performance. Let’s look at how Optimizely Graph and Content Delivery API help solve those. <h3>Content delivery & performance</h3> Content Delivery API is a well established feature of Optimizely PaaS CMS that can be used to fetch data about content. It’s installed as a NuGet package and easily configured - <a href="https://docs.developers.optimizely.com/content-management-system/v1.5.0-content-delivery-api/docs/quick-start">Content Delivery API - Quickstart</a> <img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXf7DLhLfoSlKwP0RjCUC6Zj7YMIn-oUtXeMdqB9jaB83-uRQ3s70X72uXOuvoIbS4h4w49QOtkQUeeO2nPNLpkbUMpgGAtAVVySvyhGATy7OkaEBW9IemV3uVAwhiQHz84t9CJWrA?key=3mOZlVv2ZwJhbbBj73lCAg" width="602" height="476" /> Optimizely Graph extends this concept by introducing an additional layer that operates independently of your CMS instance-similar to how Optimizely Search & Navigation works. It pulls content from your CMS using the Content Delivery API and builds a GraphQL-powered index that serves as the foundation for flexible and efficient content delivery. <img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXd-lkukdRC-fHj-upi0YW_TPFLjyz2Gh4yubEm8sJLkoUTyVJf8g8WC35A4Wp9-etxrlnhD7AyjRtwFqkz3e9YugQZnsj5loEoqJS5Pl-6I-vchaat0oCzBsFV7gtq-JLBF1LQY?key=3mOZlVv2ZwJhbbBj73lCAg" width="602" height="660" /> This difference affects how data is being fetched and has a huge impact on scaling possibilities of your solution. While using only Content Delivery API your CMS must scale with your traffic. More frontend traffic = more load on your CMS. For more demanding sites this might be very price inefficient from both CMS licensing and infrastructure costs perspective. <img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXee5qNpXTlSDDxXa3wzZrILySd-slqBlvhN7LItWTH-uaW0KkRNsCDXo0suiaBo0j6YEkkQ_pcja2nAEVQTRmNPzskQB2e66VaaTRxiT9tiUWgIHw_biX93DB8RQb-CwZa-CTf7?key=3mOZlVv2ZwJhbbBj73lCAg" width="602" height="584" /> With Optimizely Graph requests go to an external, managed service. Your CMS publishes content to the Graph service, and that service handles scaling independently. This offloads traffic from your CMS and improves resilience. <img src="https://lh7-rt.googleusercontent.com/docsz/AD_4nXcupJT5qQWToIIPdwPxd2-3L9toXp4sxLrEDaKTQensjs7TxObJo77wZjAgivv80v9ADZNHxHOZqzKgbdIfpByhxFK1ABeYH7LOrq52MAD9njgcLB08HMpRh_2TF3CDQS5lXOZK?key=3mOZlVv2ZwJhbbBj73lCAg" width="602" height="689" /> <h3>Avoiding Data Over-Fetching</h3> Reducing the size and number of requests matters in any modern frontend. A typical page might include nested blocks and related media - and fetching that efficiently is key. Content Delivery API <ul> <li> In some cases you’ll need to customize your CDA responses to expand data structures (<a href="https://support.optimizely.com/hc/en-us/articles/31961628652173-Expanding-Nested-Block-for-Content-Delivery-API-v3-CMS-12">Expanding Nested Blocks – Optimizely Docs</a>) or enrich data being returned </li> <li> It works, but requires effort and custom configuration. </li> </ul> Optimizely Graph <ul> <li> GraphQL’s design shines here. </li> <li> You can define exactly which fields, blocks, and media you want in one query. </li> <li> Great for reducing payloads and avoiding over-fetching. </li> </ul> <h3>Routing</h3> Regardless of the front-end framework you’re responsible for routing in a headless setup. You need to map frontend routes to your Optimizely content structure. Content Delivery API Supports built-in URL resolution via: <code>/api/episerver/v3.0/content?contentUrl=/about-us</code> This makes it easier to match CMS structure without writing custom logic. Optimizely Graph You can use the ContentLink property, which is indexed by Optimizely Graph by default, to locate the page that matches a given URL. Query: <pre class="language-javascript"><code>SitePageData( where: { ContentLink: { Url: { eq: "url-to-your-page" } } } )</code></pre> Response: <pre class="language-javascript"><code>"data": { "SiteBasePage": { "items": [ { "ContentLink": { "Url": "/en/exploring-the-future-of-education-the-rise-of-online-learning-platforms/" } } ] } }</code></pre> Alternatively you could implement similar solution as in Optimizely SaaS where each page contains a metadata Url property: Query: <pre class="language-javascript"><code>BlogPostPage { items { _metadata { url { default base graph hierarchical internal type } } } }</code></pre> Response: <pre class="language-javascript"><code>"data": { "BlogPostPage": { "items": [ { "_metadata": { "url": { "default": "/insights/the-benefits-of-downsizing-in-retirement/", "base": "https://<your-site-base-url>", "graph": "graph://cms/BlogPostPage/5964702069e64c42ae151861858f0aa7", "hierarchical": "/insights/the-benefits-of-downsizing-in-retirement/", "internal": "cms://content/5964702069e64c42ae151861858f0aa7?loc=en&ver=20", "type": "HIERARCHICAL" } } } ] } }</code></pre> <h3>On-Page Editing</h3> One of the standout features of Optimizely CMS is its on-page editing, which allows content authors to see changes live as they work. However, in a fully headless setup, this editing experience doesn’t come for free. In both Content Delivery API and Optimizely Graph approaches, on-page editing requires custom implementation to integrate with the CMS editor and preview modes. Content Delivery API Using CDA, you can support on-page editing by configuring your front-end app to detect Optimizely’s Edit Mode and handle it accordingly. Key requirements include: <ul> <li> Supporting query parameters like <code>?epieditmode=true and ?id=123</code> </li> <li> Resolving content in preview or draft mode </li> <li> Ensuring that URLs resolve properly to content in CMS edit view </li> </ul> A helpful reference implementation can be found here: <a href="https://hacksbyme.net/2023/06/13/on-page-editing-with-optimizely-cms-on-an-externally-hosted-site">On-page editing with Optimizely CMS on an externally hosted site</a> This setup allows content editors to use the familiar CMS UI while seeing a live rendering of content changes on your front-end app - provided it's properly connected via CDA. Optimizely Graph Optimizely Graph also supports on-page editing, but in a slightly different way. The key concept is that Graph receives published and preview content from the CMS, and you can query that using specific parameters or endpoints. To enable on-page editing, you’ll need to: <ul> <li> Configure your front-end to recognize CMS editor states </li> <li> Support preview tokens or versions (e.g., previewing unpublished content) </li> <li> Adjust GraphQL queries to fetch content in preview mode </li> </ul> Detailed documentation and setup guide available here: <a href="https://docs.developers.optimizely.com/platform-optimizely/v1.4.0-optimizely-graph/docs/on-page-editing-using-content-graph">On-page editing using Optimizely Graph</a> While Graph adds more flexibility in querying and rendering, it also requires a deeper understanding of how preview states are handled across the CMS and Graph layers.  <h3>Search Capabilities</h3> Both Optimizely Graph and the Content Delivery API support search, but the mechanisms and features differ significantly. Content Delivery API <ul> <li> Built on Search & Navigation (formerly Find) </li> <li> Supports free-text search </li> <li> Doesn’t support semantic search </li> <li> Enables personalized search results (visitor groups) </li> <li> API offers only basic filtering and ordering. To utilize more sophisticated features like boosting a custom implementation of search API and Search & Navigation on the BE side is needed. </li> </ul> Optimizely Graph <ul> <li> Doesn’t require Search & Navigation </li> <li> Supports free-text and semantic search </li> <li> Offers advanced search out-of-the-box (boosting, filters, autocomplete, and more) </li> <li> No personalization support (as of now) </li> <li> Offers greater flexibility, as search can be implemented on either the front-end or back-end, depending on your architecture. </li> </ul> <h3>Licensing</h3> Licensing costs will ultimately depend on your Optimizely contract, but there are some structural differences worth noting when choosing between CDA and Graph. Content Delivery API <ul> <li> May require a separate license for Search & Navigation </li> <li> More frontend traffic usually means more CMS app instances → higher infrastructure costs for self-hosted solutions </li> <li> More CMS instances = potentially more base licenses required </li> </ul> Optimizely Graph <ul> <li> May require a separate license for Optimizely Graph </li> <li> Content is delivered via a scalable managed service, reducing the load (and cost) on the CMS </li> <li> No need for Search & Navigation license </li> <li> Can reduce the number of required CMS licenses, especially in high-traffic apps </li> </ul> <h3>Summary</h3> <div align="left"> <table style="width: 43.3987%; height: 439.532px;"> <tbody> <tr style="height: 47.5938px;"> <td style="width: 26.2349%; height: 47.5938px;"> Feature </td> <td style="width: 41.5832%; height: 47.5938px;"> Content Delivery API (CDA) </td> <td style="width: 32.1243%; height: 47.5938px;"> Optimizely Graph </td> </tr> <tr style="height: 47.5938px;"> <td style="width: 26.2349%; height: 47.5938px;"> API Type </td> <td style="width: 41.5832%; height: 47.5938px;"> REST </td> <td style="width: 32.1243%; height: 47.5938px;"> GraphQL </td> </tr> <tr style="height: 47.5938px;"> <td style="width: 26.2349%; height: 47.5938px;"> Scaling </td> <td style="width: 41.5832%; height: 47.5938px;"> Tied to CMS instance </td> <td style="width: 32.1243%; height: 47.5938px;"> External managed service </td> </tr> <tr style="height: 47.5938px;"> <td style="width: 26.2349%; height: 47.5938px;"> Routing </td> <td style="width: 41.5832%; height: 47.5938px;"> Built-in URL resolution </td> <td style="width: 32.1243%; height: 47.5938px;"> Custom slug/url-based </td> </tr> <tr style="height: 67.1875px;"> <td style="width: 26.2349%; height: 67.1875px;"> Nested Content Fetch </td> <td style="width: 41.5832%; height: 67.1875px;"> Custom config required </td> <td style="width: 32.1243%; height: 67.1875px;"> Native via query </td> </tr> <tr style="height: 47.5938px;"> <td style="width: 26.2349%; height: 47.5938px;"> Search </td> <td style="width: 41.5832%; height: 47.5938px;"> Search & Navigation (optional) </td> <td style="width: 32.1243%; height: 47.5938px;"> Built-in, semantic </td> </tr> <tr style="height: 47.5938px;"> <td style="width: 26.2349%; height: 47.5938px;"> Personalization </td> <td style="width: 41.5832%; height: 47.5938px;"> Supported </td> <td style="width: 32.1243%; height: 47.5938px;"> Not supported </td> </tr> <tr style="height: 67.1875px;"> <td style="width: 26.2349%; height: 67.1875px;"> On-page Editing </td> <td style="width: 41.5832%; height: 67.1875px;"> Supported with setup </td> <td style="width: 32.1243%; height: 67.1875px;"> Supported with more setup </td> </tr> </tbody> </table> </div>   Content Delivery API Pros: <ul> <li> Popular and well known REST approach </li> <li> Easier routing with built-in URL resolution </li> <li> Doesn’t require additional licenses </li> </ul> Cons: <ul> <li> Need to scale with your CMS </li> <li> Custom configuration required for some data fetching scenarios </li> </ul>   Optimizely Graph Pros: <ul> <li> Query exactly what you need </li> <li> One request for nested blocks, media, etc. </li> <li> More efficient, flexible, and scalable </li> <li> Great for modern front-end frameworks </li> </ul>  Cons: <ul> <li> More complex routing based on content url or slug. </li> <li> May require separate license </li> </ul> <h3>Final Thoughts</h3> Going headless with Optimizely unlocks a lot of freedom and flexibility. Whether you choose CDA or Optimizely Graph - you're in a great place to build fast, modern, and scalable experiences. Got questions or experiences with either? I’d love to hear your take! 2025-06-02T09:15:50.0000000Z

Blog post

Going Headless - Optimizely Graph vs Content Delivery APIComparison of Optimizely Graph vs Content Delivery API for headless CMS delivery.2025-06-02T00:00:00.0000000Z

Blog post