Brightspot CMS Developer Guide

Tutorial: Hello World GraphQL Content API

15 minutes
Estimated Time

In this tutorial, you will create and query a Hello World endpoint using the GraphQL Content API (GCA). As part of this process, you will create a content type and publish assets that you will query for using the GraphQL explorer.

This tutorial has two tracks depending on how you want to complete it:

  • Editorially—An option for those who want to complete this tutorial solely in Brightspot.
  • Programmatically—An option for those who want to complete this tutorial in both an IDE and Brightspot.

As part of the effort, you will complete the following steps:

  1. Create a content type called Post and publish two assets from it.
  2. Create a GCA endpoint and configure it so that it allows queries of Post assets.
  3. Use the GraphQL explorer to fetch data from assets of the Post type.

Assumptions

This tutorial assumes the following:

  • Familiarity with GraphQL
  • Familiarity with the editorial process of creating a content type in Brightspot

Step 1: Creating a content type and publishing assets

Create a content type Post using one of the two methods described in the module below. After doing so, publish two assets in Brightspot of the Post content type. You will query for these assets later in this tutorial.

Note
If desired, you can complete this tutorial using a pre-built content type supplied with your Brightspot build, like Article.

Creating a content type editorially

In Brightspot, do the following:
  1. Click menu > Admin > Content Types.
  2. In the Name field, enter Post.
  3. Under Items, click add_circle_outline Add, then select Text Field.
  4. In the text field's Name field, enter Message.
  5. Click Save.

Creating a content type programmatically

In your IDE, do the following:
  1. Create a new Java class called Post.
  2. Add a string field called message.
For an example, refer to the code snippet below.
import com.psddev.cms.db.Content;

public class Post extends Content {

    private String message; 
}

Publishing assets

  1. Depending on the path you take to reach this step, do one of the following:

    • Editorially—Navigate to the dashboard.
    • Programmatically—Log into Brightspot.
  2. In the header, click add.
  3. From the Misc Content Types list, select Post.
  4. In the Message field, enter This is my first message.
  5. Click Publish.
  6. Click more_horiz, located to the right of the Publish button, and then select Copy This Post.
  7. In the Message field of the new asset draft, enter This is my second message.
  8. Click Publish.

You now have two assets of the Post content type you created that you will query later in this tutorial.

Step 2: Creating and configuring a basic GraphQL Content API endpoint

In this step, you will create a basic GraphQL endpoint using one of the two methods described in the module below, and then configure the endpoint such that it allows queries for assets of the Post content type.

Creating and configuring an endpoint editorially

In Brightspot, do the following:
  1. Click menu > Admin > APIs.
  2. In the left rail, from the Endpoints list and under the Create menu, select GraphQL Content API, then click New.
  3. In the Name field, enter Hello World as the name for the endpoint. This is an internal name used to reference the endpoint in the Endpoints list in the left rail.

    Note
    After naming the endpoint, Brightspot automatically generates a draft of the endpoint’s path. Endpoint paths are tied to Brightspot's permalink system and associated with the Global site, which ensures that an endpoint’s path is not a duplicate. If a duplicate exists upon trying to save the endpoint, indicates this in an error message and prevents you from saving.
  4. In the Path field, verify that /graphql/content/hello-world is automatically generated from the Name field. Your edit page looks similar to the following image.

    New GCA endpoint.png New GCA endpoint.png
  5. From the Schema Settings field, under Read/Write Content Types, select Post. By doing this, you are restricting the endpoint to only fetching Post assets.
  6. Expand the Database Queries cluster, then toggle on Allow Database Queries.
  7. Click Save.
    Note
    After saving the endpoint, the Paths field at the bottom of this edit form displays the same path as the one auto-generated from the Name field; the Paths field exists so that you know the endpoint path even when the endpoint is created programatically.

Creating and configuring an endpoint programmatically

In your IDE, do the following:
  1. Create a new Java class called Hello World.
  2. Extend GCAEndpoint to designate the class as a GCA endpoint.
  3. Implement Singleton to ensure there is only one record.
  4. Define the endpoint path.
  5. Define the schema settings.
  6. Assign Post.class as a read/write entry class.
For an example, refer to the code snippet below.
import java.util.Set;

import com.psddev.dari.db.Recordable;
import com.psddev.dari.db.Singleton;
import com.psddev.graphql.gca.GCAEndpoint;
import com.psddev.graphql.gca.GCASchemaSettings;

@Recordable.DisplayName("Hello World")
public class HelloWorld extends GCAEndpoint implements Singleton {
      
    @Override
    public Set<String> getPaths() {
        return Set.of("/graphql/content/hello-world");
    }
    
    @Override
    protected GCASchemaSettings getSchemaSettings() {
        return GCASchemaSettings.newBuilder()
            .mutableEntryClass(Post.class)
            .build(); 
    }
}
  • Sets the name of the endpoint to Hello World.
  • Defines the Java class as a GCA endpoint and ensures only one record of it is created.
  • Defines the GCA endpoint path.
  • Assigns Post.class as a read/write entry class.

Step 3: Querying for Post assets

You can now use the GraphQL explorer to query for Post assets.

  1. Depending on the path you take to reach this step, do one of the following:
    • Editorially—Continue to step 2 (as you are already on the endpoint edit page).
    • Programmatically—In Brightspot, do the following:
      1. Click menu > Admin > APIs.
      2. From the Endpoints list on the left, select the Hello World endpoint you created.
  2. In the top right of the screen, click more_horiz, then click GraphQL Explorer.
    Note
    Your role must have developer permissions in order to use the GraphQL explorer. For details, see Creating a role.
  3. In the query panel in the middle, paste the following query:
    query MyQuery {
      Query {
        Records(from: {type: Post}) {
          ... on QuerySelect {
            __typename
            items {
              ... on Post {
                __typename
                _id
                message
              }
            }
          }
        }
      }
    }
  4. Execute the query by clicking the Play icon. Your result should look similar to the following code snippet.
    {
      "data": {
        "Query": {
          "Records": {
            "__typename": "QuerySelect",
            "items": [
              {
                "__typename": "Post",
                "_id": "00000191-be89-d8ae-abf1-fe9b8e9b0000",
                "message": "This is my first message"
              },
              {
                "__typename": "Post",
                "_id": "00000191-be8a-d8ae-abf1-fe9b5c090000",
                "message": "This is my second message"
              }
            ]
          }
        }
      }
    }
Tip
Brightspot extends some of the GraphQL Explorer's native capabilities, helping you more easily query the schema. See below for more information:

From the Query Panel:
  • Prettify Query—Reverts the query back to its more formatted version.
  • Minify Query—Condenses the size of the query to a single line that you can scroll.
  • Merge Fragments—Merges any fragments you have created into the query.
  • Copy Query—Copies the query to the clipboard.
  • Toggle Wrap Query—Wraps a minified query around to the next line, avoiding scrolling.
  • Toggle Deprecated Fields—Hides fields that have been deprecated.

You have now created a Hello World endpoint using the GraphQL Content API (GCA), and configured it such that you can now use it to query for content.

Note
You can view additional data about your endpoint now that you have queried it. Back on the endpoint's edit page, the Advanced tab displays information about schema load and history.

Previous Topic
Tutorial: Creating and expanding access for a GraphQL endpoint inside of Brightspot
Next Topic
Accessing the GraphQL explorer
Was this topic helpful?
Thanks for your feedback.
Our robust, flexible Design System provides hundreds of pre-built components you can use to build the presentation layer of your dreams.

Asset types
Module types
Page types
Brightspot is packaged with content types that get you up and running in a matter of days, including assets, modules and landing pages.

Content types
Modules
Landing pages
Everything you need to know when creating, managing, and administering content within Brightspot CMS.

Dashboards
Publishing
Workflows
Admin configurations
A guide for installing, supporting, extending, modifying and administering code on the Brightspot platform.

Field types
Content modeling
Rich-text elements
Images
A guide to configuring Brightspot's library of integrations, including pre-built options and developer-configured extensions.

Google Analytics
Shopify
Apple News