Solutions
Brightspot Headless CMS

Inside Brightspot: How GraphQL queries work

GraphQL, a query language for APIs used in many headless CMS implementations, has enjoyed much popularity in recent years as companies look for ways to remain competitive and appealing to their audiences in an ever-changing technological landscape. But what does GraphQL actually look like, and how is it used?

At Brightspot, we find that the best way to demonstrate GraphQL is to show you how we use it.

Brightspot offers two types of configurable GraphQL APIs, which we have named:

With light configuration, GraphQL schemas are automatically generated and updated with each change to relevant data models and business logic.

We use our CMA for CRUD—create, read, update and delete—functions since it exposes the ability to do so directly on Brightspot data models via GraphQL queries. This tool would be useful for creating something like, for example, an iOS widget for editors in your organization to perform simple tasks without having to log into the main Brightspot interface.

Our CDA enables us to utilize GraphQL queries in order to fetch processed data from view models. Like the CMA, the CDA can also be used to perform CRUD operations, but its ability to specify business logic makes it useful for building APIs that are safe for third-party consumption. The CDA is also useful for delivering data to front-end experiences for end users, whether that be via website, native mobile app, or another kind of experience (think: Internet of Things).

What sets Brightspot apart from other CMS platforms that utilize GraphQL? It’s the fact that we are built on an extensible architecture that offers ultimate flexibility to choose headless, decoupled, hybrid or headless CMS as your approach.

Let’s take a look at the CMA and CDA in action.

Brightspot’s GraphQL CMA

In the code snippet below, we have built out an Author content type. This content type has a few string fields, like First Name, Last Name and Biography.

screenshot of code with GraphQL query

In the snippet below, we also have an Address field which is modeled like a normal U.S. address (Address Line 1, Address Line 2, City, State, Zip Code).

screenshot of code with GraphQL query

In the snippet below, we also have a third type that represents any published works the author might have, and it is comprised of the Title and URL of the work. Lastly, we have an indexed field of Author that allows work to point to the author that penned it.

screenshot of code with GraphQL query

Now let’s see these models in action. If we jump into Brightspot, we will see the Author content type is automatically generated and modeled exactly how we set it up in the code (see the image below).

screenshot of Brightspot GraphQL query interface

If we were to make any changes to the modeling code, the UI will automatically update, and any necessary database changes will also be handled automatically—one less thing a developer has to worry about.

Now let’s take a look at the Work content type. As you can see in the image below, the UI represents the class we built out in code.

screenshot of Brightspot GraphQL query interface

Now, let’s go into the API section of the CMS and configure the CMA. In the image below, you can see that we have very simply created a new CMA, named it Author Management (which automatically generates a path that we can change if desired), and designated Author and Work read types.

screenshot of Brightspot GraphQL query interface

Now that we have configured the CMA, let’s take a look at the GraphQL section of Brightspot. In the image below, you will see the CMA we just configured.

The two APIs—Author and Work—have been automatically generated. Let’s dive into the Author API and take a look at the typical structure of CMA queries in Brightspot.

screenshot of Brightspot GraphQL query interface

As you can see, Author and Work are structured the same because we want to give the user the ability to specify an ID to fetch a specific record. If they don’t want to specify an ID, we have Limit and Offset, which can be used for paginating through results. We also have Predicate and Sorts for more granular control over the results that we retrieve.

In the Items field—which has items that represent instances of an author in this content or instances of whatever content we are querying for—we are going to select the following fields:

  • First Name
  • Last Name
  • Biography
  • Address Line 1
  • City
  • State
  • Zip Code

And then we will run the query.

screenshot of Brightspot GraphQL query interface

GraphQL has a term, “shape,” that is used to point out field order and structure. Notice in the image above that the response mirrors the same shape as its query. That way, developers on the receiving end know exactly what to expect in terms of what is returned.

“On the fly” data modeling

One of the reasons developers love using Brightspot is because we allow you to do “on the fly” data modeling and query on those rapidly changing models live.

Let’s take another look at the code for this CMA.

screenshot of GraphQL query code

Let’s say that a third party was using the CMA above to ingest author records, but it uses an Author ID field (which currently, this CMA does not include). So, in order to fix this missing field, we can simply add it to the CMA, highlighted in red in the image below.

screenshot of GraphQL query code

Now that we’ve added Author ID to our CMA, let’s refresh the schema viewer and take a look at the change.

screenshot of Brightspot GraphQL query interface

Highlighted above, the Author ID field is now included.

We were able to make this change and see it reflected in the schema viewer without having to go through an entire build process, saving developers significant time.

If you refer back to the CMS UI, you will see that it has automatically been updated as well.

screenshot of GraphQL query interface

Brightspot’s GraphQL CDA

Now that we’ve taken a look at our GraphQL CMA, let’s take a look at our GraphQL CDA. Let’s begin by looking at View Models since those are the types of classes from which these APIs are generated.

In the image below, you’ll see the same Author View Model that we saw in the CDA portion of this demo above.

screenshot of GraphQL query code

Suppose your organization did not want to expose the author's address, but still wanted readers to have some idea of their location. This is how the view model is set up above—it will pass only the author's State (as well as their Biography, First Name, and Last Name.

In the image below, we have the Work field that queries for an author’s works and returns Work view models.

screenshot of GraphQL query code

Lastly, we have an Author Search view model, seen in the image below.

screenshot of GraphQL query code

The two fields at the top—Search and Limit—will become GraphQL arguments for our Author Search field that this view model will surface, and this search will be used to filter down on author results more.

Now let’s go back into Brightspot, specifically to the API section of the CMS, and create a GraphQL CDA. We will name it Author Delivery and select AuthorSearchViewModel and AuthorViewModel as the Query Entry View Classes.

screenshot of Brightspot GraphQL query interface

Back in the GraphQL query viewer tool, you can now visualize the CDA we just created. As with the CMA we created, the CDA has fields that automatically match the view model that we created. Let’s query for results of the authors that are in the system.

screenshot of Brightspot GraphQL query interface

One of the huge benefits of using Brightspot is that in addition to these powerful features, we also allow you schema viewing features that help you see the relationship between the data structures you create—especially when things become complex.

Additional Brightspot Tools

Database and Schema Viewers for data models, view models

One of the huge benefits of using Brightspot is that in addition to these powerful features, we also allow you database and schema viewing features that help you see the relationship between the data structures you create—especially when things become complex.

screenshot of Brightspot Dari interface
screenshot of Brightspot Dari interface

Javadocs explorer for additional context

Brightspot also offers developers a docs explorer feature that adds additional context to the queries in the GraphiQL schema viewer.

example of Brightspot GraphQL query interface

This enables developers to dive deeper into the query fields. If a developer is querying for a location, for example, that location may be ambiguous. Thanks to Javadocs, the developer will know that the query returns the author's State location for privacy purposes, as shown in the image above.

These kinds of annotations are also visible in the code.

example of Brightspot GraphQL query code


To see a developer write GraphQL queries in real time, check out our GraphQL webinar featuring Brightspot’s head GraphQL specialist, Omavi Walker.

Share

Related resources

October 08, 2020
An API-first CMS provides the advantages of headless CMS—API-only—with rich capabilities like workflow, search and content delivery. With an API-first platform, businesses have the option to use a number of pre-built integrations to save valuable development time and effort.
4 Min Read
By Brightspot Staff
January 18, 2021
GraphQL is a query language that enables the connection of programming APIs that enable headless CMS integrations like those possible through the Brightspot Content Business Platform. For digital-media teams, GraphQL supports two of the most important factors in content development: speed and flexibility.
4 Min Read
By Brightspot Staff
December 10, 2020
Headless CMS and GraphQL have been trending topics for a while in the content management space. Discover the benefits of headless CMS and the flexibility it affords digital organizations, plus the power of GraphQL as the query language connecting your APIs to your front-end applications.
3 Min Read

All Brightspot Features

The Brightspot Content Business Platform is built by publishers and developers, and is designed to grow with your business.
A robust set of tools to manage sites, content, users and permissions, workflows, languages, and analytics.
Keyword-driven and comprehensive, filterable search and taxonomy features make folders a thing of the past.
Intuitive and designed for the work, including rich-text editing and collaboration features that make teamwork work.
Start publishing content rapidly thanks to built-in, extensible content types including text assets, media, pages and much more.
Drive deeper engagement and personalized experiences by leveraging authentication, profiling, segmentation and affinity features.
Built to be a bridge to all your systems and data, start with one of the 70 plug-and-play integrations, or build your own custom integration.
Meet users where they are thanks to syndication and distribution tools like RSS, sitemaps, SEO tools, social publishing and translation support.
Front-end agnostic means businesses can publish how they want—headless or decoupled—all from the same environment.

Move your business forward with Brightspot

Get the publishing speed you need with Brightspot. Book your personalized walk-through today!