Optimizely GraphQL Basics

GraphQL is a modern API query language that lets you request exactly the data you need. Unlike traditional REST APIs, GraphQL uses a strongly typed schema to define the structure of data, making it easier to understand and interact with.

Why use GraphQL?

Traditional REST APIs have fixed endpoints like /users or /users/1/posts, each returning a predefined data structure. This can lead to

• Over-fetching, where you get too much data.
• Under-fetching, where you get too little data and need multiple requests.

GraphQL solves these issues by letting you specify the exact data shape you want in a single request.

Optimizely GraphQL for REST API developers

If you are familiar with REST APIs, here is how Optimizely Graph compares:

Optimizely Graph features a GraphQL API, that you can use for content delivery and search.

HTTP request pattern

Use the GraphQL API similarly to a REST API.

For example, you can send a POST request with a JSON body to the following:

https://cg.optimizely.com/content/v2?auth=\{yourSingleKey}

The request body is JSON, like in REST APIs. The key difference is GraphQL's strongly typed schema.

Strongly typed schema

The schema in Optimizely Graph contains one type for each content type in CMS when integrated with Optimizely Content Management System (CMS). You can filter content based on the properties that exist in the specific content type that you are querying.

REST API and GraphQL comparison

Core GraphQL concepts for Optimizely Graph

Queries only (No mutations or subscriptions)

Optimizely Graph focuses on queries based on the strongly typed schema. It does not support mutations (writing data) or subscriptions (real-time updates).

# Queries for reading data – Available
query GetArticles {
  ArticlePage {
    items {
      Name
      TeaserText
    }
  }
}

# Mutations for writing data – Not available in Optimizely Graph
mutation CreateArticle {
}

# Subscriptions for real-time updates – Not available in Optimizely Graph  
subscription ArticleUpdates {
}

Input and output types

Each content type has an input type for filtering, searching, and ordering, and an output type for the data you receive. The following is an example for a blog site:

query BlogListingPage($author: String, $topics: [String]) {
  BlogPostPage(
    where: {
      ArticleAuthor: { eq: $author }    # Input type for filtering
      Topic: { in: $topics }            # Input type for filtering
    }
  ) {
    items {
      # Output type - the data you get back
      Heading
      ArticleSubHeading
      BlogPostBody {
        html
      }
      ArticleAuthor
      Topic
    }
  }
}

Content type structure

Each content type in your CMS becomes a queryable GraphQL type. The following example shows how to query specific content types:

# Query specific content types
query {
  ArticlePage {        # Maps to ArticlePage content type
    items {
      Name
      TeaserText
      MainBody
    }
  }
}

query {
  StandardPage {       # Maps to StandardPage content type  
    items {
      Name
      MainBody
      MetaTitle
    }
  }
}

Next steps

Now that you understand the core GraphQL concepts for Optimizely Graph, you are ready to explore specific functionality in more detail. You should start with Filtering Data to learn how to retrieve specific content, then progress through sorting and search to build comprehensive content delivery solutions.

Essential query skills

• Filtering data – Learn how to filter content with where clauses, operators, and complex logic.
• Sorting results – Master sorting techniques for consistent, performant data retrieval.
• Search functionality – Implement a powerful text search with relevance and semantic ranking.

Data management

• Pagination – Handle large datasets efficiently with skip/limit and cursor-based pagination.
• Multi-language content – Work with localized content across different languages and regions.

Advanced techniques

• Fragments and aliases – Optimize queries with reusable fragments and handle complex content structures.
• Faceted search and summarization – Build advanced filtering interfaces with facet counts.

Practical implementation

• Error handling – Implement robust error handling for production applications.
• Development tools – Use GraphiQL and other tools to develop and debug queries efficiently.