Xperience by Kentico Headless channel & Next.js: GraphQL API (Part 3)

Continuing our exploration of the Xperience by Kentico Headless channel and its integration with Next.js, we now turn our attention to exposing data through the GraphQL API. In the previous article, we set up the Headless channel and prepared the content to be served via the API. In this article, I’ll walk you through the steps needed to expose the GraphQL API in Xperience by Kentico and create your first GraphQL query to retrieve data.

It’s worth introducing what GraphQL actually is. Until now, I have primarily worked with REST APIs, which typically serve a similar purpose as GraphQL does. However, since Xperience by Kentico exclusively supports GraphQL, we have no choice but to dive in and explore its capabilities.

🕸️ What is GraphQL?

GraphQL is a modern query language and runtime for APIs that enhances flexibility and efficiency in data fetching. Unlike traditional REST APIs, which often require multiple endpoints for different data needs, GraphQL uses a single endpoint, enabling clients to request precisely the data they need. This approach reduces network overhead, speeds up response times, and simplifies development.

GraphQL’s vendor-agnostic and developer-friendly nature makes it a versatile solution that integrates seamlessly with modern frameworks. It offers a future-proof approach to building scalable, dynamic digital experiences. Many headless CMS platforms, such as Kontent.ai, now provide native GraphQL APIs, empowering businesses to deliver streamlined and personalized customer experiences.

Xperience by Kentico adopts a hybrid approach and offers a GraphQL API as well. However, the current implementation comes with some limitations that are worth noting.

🤝🏻 What does the Xperience by Kentico GraphQL API offer?

In general, GraphQL is built around three core features: Queries, Mutations, and Subscriptions.

• Queries are used for retrieving data from the GraphQL server.
• Mutations allow updating data on the server.
• Subscriptions enable listening for data updates on the server, which is particularly useful for scenarios like cache revalidation in your app.

Currently, Xperience by Kentico supports only Queries for data retrieval. Subscriptions were previously on the roadmap, but it seems they have been deprioritized. Support for Mutations has never been mentioned.

📍 Setting up GraphQL in Xperience by Kentico

Having covered the basics of GraphQL and its features in Xperience by Kentico, we can now move on to the setup process and implementation details. This article picks up where we left off in the previous one.

Configuration

First, we need to add configuration keys to the appsettings.json file. For now, we'll focus on the key required for our exploration. In a real project, however, you might need to include additional keys to override defaults for caching, security, or other purposes—refer to the documentation for details.

To begin, add the following key to your appsettings.json file in the Xperience by Kentico project. This will enable us to view the schema and query data using the built-in UI tool:

  "CMSHeadless": {
    "AllowIntrospection": true
  }

Endpoint

GraphQL queries are submitted via the HTTP protocol. To make these requests, you’ll need the following:

• API endpoint for the URL
• API key for the Authorization header, using a Bearer token

GraphQL API Endpoint

To obtain the API endpoint:

1. Go to the Channel management application in the Xperience by Kentico Admin interface.
2. Select your headless channel.
3. Locate the GraphQL API endpoint label, where you’ll find the endpoint (e.g., /graphql/400b3f2d-f091-46b2-9340-55bd16c0bfb6).

The full URL for API requests will use the following format:
http://localhost:<port>/graphql/<guid>

API Key

To create the API key:

1. Navigate to the API keys tab in the same section.
2. Click New key and provide a name of your choice.
3. Set the access type to Headless Content - Published.
4. Click Generate to obtain the key.

You’ll receive the API key—be sure to copy and store it securely, as it won’t be accessible again.

Next, we’ll use the UI tool to query our data.

First Query

Xperience by Kentico includes a built-in UI tool that allows you to browse the API schema, build queries, and test them by making API requests. This tool is accessible through a web browser at a URL in the following format:
http://localhost:<port>/graphql/ui.

Upon navigating to this URL, you’ll see a welcome page. Click the Create Document button to open an environment where you can test the API. However, before creating a query, you’ll need to adjust the connection settings to link the tool to your API.

Configuring the UI Tool

1. Click the cogwheel icon in the upper-right corner to open the settings.
2. In the Connection Settings:
   • Go to the General tab and set the Schema Endpoint to the endpoint value you obtained earlier.
   • Switch to the Authorization tab, select the Bearer type, and enter your API key in the Token field.
3. Click Apply to save the settings.

The UI tool is now configured and ready to query the API.

Creating and Running a Query

1. In the Builder section, click the plus icon to create a new query and name it CampaignPage.
2. Use the Builder section to explore the structure of your data. By ticking the checkboxes, you can add relevant fields to the query. These fields will appear in the Request section.
3. Click the Run button to execute the query against the API. The result will appear in the Response section.

Feel free to experiment and adjust the query as needed during testing. Later in this series, I’ll outline the specific query we’ll use in the Next.js application.

Making Requests via HTTP

GraphQL queries can also be sent via HTTP POST requests using tools like Postman or Thunder Client. The JSON request body should follow this format: {"query": "<your-query>"}

Ensure that your query string is free of unnecessary whitespace to maintain JSON validity.

🛤️ Next Up

With the setup in Xperience by Kentico complete, we’ll move on to working with Next.js. In the following parts of this series, we’ll explore how to make requests and render data within the framework.