Skip to main content

GraphQL

What is GraphQL?​

GraphQL is a query language for APIs that lets clients request exactly the data they need in a single request. Unlike traditional REST APIs that return fixed data structures from multiple endpoints, GraphQL provides a strongly-typed schema where clients can specify their data requirements and receive precisely that data back. This means more efficient data fetching, better performance, and improved developer experience through features like introspection and type safety.

For a deeper introduction to GraphQL concepts, visit graphql.org or the GraphQL specification.

What is the GraphQL plugin for?​

The GraphQL plugin provides API endpoints conforming to the GraphQL specification served by Brightspot CMS, along with a framework for configuring and building custom endpoints, and a suite of tools to aid in the development, testing and deployment of your endpoints using industry best practices.

The GraphQL Content API (GCA) is the cornerstone of this plugin, as it provides programmatic access to all your Brightspot content types and view models, with functional and data access controls governed by a simple editorial or code based configuration. This endpoint can support the following use cases:

Headless CMS implementations

Decoupled frontends (React, Vue, Next.js, mobile apps) that fetch content from Brightspot.

Multi-channel content delivery

Serving the same content to web, mobile, IoT devices, or third-party platforms.

Custom editorial tools

Internal applications that require programmatic access to content and metadata.

Content syndication

Exposing content to external partners or customers through a controlled API.

Content ingestion

Importing content from external systems, bulk operations, or automated content pipelines via mutations.

The GraphQL Explorer, built on top of GraphiQL, is the primary development and testing GUI tool for your GraphQL APIs, embedded directly into Brightspot CMS. It provides a zero-setup development environment where teams can test queries, browse auto-generated documentation, and share queries with colleagues—all without writing any client code. Whether you're a developer building an API or a team member consuming one, the Explorer makes GraphQL accessible and productive from day one.

GraphQL Explorer

Approaches​

The plugin offers four approaches to building GraphQL APIs, each suited to different use cases and levels of customization.

GraphQL Content API (GCA)​

Recommended for most projects

The GCA is an out-of-the-box GraphQL endpoint that automatically exposes all your content types and view models through a feature-complete API. It offers full parity with the capabilities available in the CMS UI and Java APIs, with configurable access controls and zero required code. This is the recommended approach for most projects because it requires zero to minimal code while providing comprehensive content access.

When to use the GCA:

  • You want a headless CMS API without writing schema definitions.
  • Your API structure can follow your content model.
  • You want to expose business logic encoded in view models or static methods.
  • You need full CRUD operations on content.
  • You want built-in support for filtering, sorting, pagination, and search.
  • You want to ingest content from external systems.

Key capabilities:

  • Automatic schema generation from content types, view models, and static methods
  • Automatic documentation from Java code comments exposed in GraphQL schema
  • Query all content with filtering, sorting, and pagination
  • Full create, read, update, and delete operations
  • Reference resolution and relationship traversal
  • Image transformations and responsive image support
  • Rich text rendering with embedded content
  • Preview modes and workflow integration
  • Site-specific and multisite content access

Configuration level: Low — CMS configuration through the Brightspot UI, or via a simple Java class serving as configuration as code.

GraphQL code generator​

For hand-crafted schemas

The code generator is a tool that converts a static GraphQL schema definition (SDL) into type-safe Java code, providing the scaffolding for a fully functional GraphQL endpoint. You focus on implementing your business logic while the generator handles the GraphQL plumbing.

When to use the code generator:

  • You have a specific schema design that does not follow your content model.
  • You're implementing an existing GraphQL schema.
  • You need complete control over types, fields, and their structure.
  • You want type safety and compile-time validation.

Key capabilities:

  • Generate Java classes from SDL files
  • Type-safe field resolvers and data fetchers
  • Support for all the main GraphQL features (queries, mutations, custom scalars)
  • Integration with Brightspot's built-in types and features
  • Focus on resolver logic, not schema wiring

Configuration level: Medium — Write SDL, implement generated resolver interfaces.

GraphQL framework​

For custom dynamic schemas

The GraphQL Framework provides low-level Java APIs for building completely custom, dynamic GraphQL schemas programmatically. This is the same framework that powers the GCA, giving you the same capabilities with full control over every aspect of your schema.

When to use the framework:

  • You need dynamic schemas that change based on external factors.
  • You're building specialized GraphQL endpoints with unique requirements.
  • The GCA and code generator do not fit your use case.
  • You want to understand or extend Brightspot's GraphQL internals.

Key capabilities:

  • Programmatic schema building with type-safe APIs
  • Dynamic type registration and schema modification
  • Full control over type resolution, field fetching, and data loading
  • Access to all framework features: built-in types, directives, instrumentation
  • Build entirely custom endpoint behaviors

Configuration level: High — Java development and GraphQL Framework knowledge required.

REST API mapping​

For REST-style API consumption

REST API mapping transforms any GraphQL endpoint (built with GCA, code generator, or framework) into REST-like path-based routes that return simple JSON responses. Your API remains GraphQL-backed under the hood, but clients consume it like a traditional REST API—no GraphQL client required, no query syntax to learn.

When to use REST API mapping:

  • Your team isn't ready to adopt GraphQL clients.
  • You want to provide a simpler entry point for consuming Brightspot content.
  • You have API consumers familiar with REST who aren't instrumented for GraphQL.
  • You need straightforward path-based requests with predictable JSON responses.

Key capabilities:

  • Define custom routes with HTTP methods (GET, POST, etc.)
  • Map each route to a GraphQL query that executes behind the scenes
  • Return standard JSON responses without GraphQL wrapper
  • Provide REST-style API access without requiring GraphQL knowledge
  • Bridge teams into GraphQL adoption gradually

Configuration level: Low — All editorial configuration through the CMS UI.

Key features across all approaches​

Regardless of which approach you choose, all GraphQL endpoints built with Brightspot share these enterprise-grade features:

GraphQL explorer

A built-in, modern GraphiQL-based interface for testing queries, browsing schema documentation, and sharing queries with team members. Includes dark mode, query history, and syntax highlighting.

Persisted queries

Improve performance and security by executing queries by ID rather than sending full query text. Supports both Automatic Persisted Queries (APQ) that register on-the-fly, and static persisted queries that you register ahead of time.

Security

Comprehensive security controls including custom authentication, authorization, query timeouts, maximum query depth limits, query complexity analysis, and rate throttling. Includes configurable introspection controls to manage schema visibility per endpoint.

Debugging

Deep integration with Brightspot's Dari profiler provides detailed insights into query execution and data fetching performance. Use the @debug directive to profile specific queries.

Analytics

Built-in metrics collection tracks API requests on a per-endpoint and per-client basis, providing insights into usage patterns. Visualize these metrics using Brightspot's built-in charts and graphs.

Schema management

Track schema changes over time with automatic versioning, compare schemas with a visual diff tool, and monitor schema load performance to ensure API availability.

Each of these features is covered in detail in the Common Features section.

Architecture​

The Brightspot GraphQL plugin architecture is built on three distinct layers that provide flexibility for different development approaches, all powered by the industry-standard graphql-java library as its foundation.

1. Foundation Layer: graphql-java

At the base of the architecture sits the graphql-java library, which handles the core GraphQL specification implementation. All Brightspot GraphQL endpoints ultimately delegate to this library for query parsing, validation, and execution.

2. Plugin Layer: Brightspot GraphQL Plugin (highlighted in red)

The plugin provides three core components that form the backbone of GraphQL support in Brightspot:

  • GraphQL Framework: A Java API layer that wraps graphql-java, providing programmatic schema building, type registration, and endpoint configuration capabilities. This framework powers both the GCA and custom endpoints.
  • GraphQL Content API (GCA) Endpoint: An out-of-the-box, zero-code GraphQL endpoint that automatically exposes all the Brightspot content of your choosing. It dynamically generates a GraphQL schema from your content types, view models, and static methods, making it the recommended approach for most projects.
  • Java Source Code Generator: A build-time tool that transforms raw Schema Definition Language (SDL) files into type-safe Java code, providing scaffolding for custom endpoints with compile-time validation.

3. Project Layer: Your Code

This layer represents the customization and content developers provide:

  • Content Types: Your Brightspot content models (articles, authors, products, etc.) that define the structure of your content. These feed directly into the GCA for automatic schema generation.
  • View Models: Presentation layer objects that transform raw content into API-ready data structures. The GCA can expose these alongside content types for flexible data shaping.
  • Static Methods: Utility methods and custom resolvers that can be integrated into the GCA schema for specialized business logic.
  • Raw SDL: Hand-written GraphQL schema definitions that describe your desired API structure independently of your content model.
  • Custom Framework Implementation: Java code that uses the GraphQL Framework directly to build fully custom, dynamic schemas programmatically.

Deprecated GraphQL APIs​

For CMA/CDA Users

If you're currently using the Content Management API (CMA) or Content Delivery API (CDA), these APIs are now deprecated. The GraphQL Content API (GCA) replaces both with a unified, more capable endpoint for all content operations.

Why migrate to GCA:

  • Single API for both content management and delivery
  • Improved performance and flexibility
  • Automatic schema generation with full type support
  • Enhanced security and granular access controls
  • Built-in filtering, sorting, pagination, and search
  • Modern tooling and active development

Ready to migrate? See Migrating from CMA/CDA to GCA for step-by-step guidance on upgrading your implementation.