Optimizely GraphQL basics

8 min

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.

Reasons to use GraphQL

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

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, send a POST request with a JSON body to the following endpoint:

https://cg.optimizely.com/content/v2?auth=YOUR_SINGLE_KEY

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

REST API	GraphQL
Multiple endpoints (/api/articles, /api/pages).	Single endpoint (/content/v2).
Fixed response structure.	Flexible, request only needed fields.
Over-fetching common.	Get exactly what you request.
Multiple requests for related data.	Single request with nested data.
No built-in type system.	Strongly typed schema.

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
    }
  }
}