Best Practices

Operational guidance for running Brightspot GraphQL endpoints in production. For schema-design and API-shape guidance specific to the GCA, see GCA Best Practices; this page covers the concerns common to every endpoint kind: deployment, schema change management, monitoring, and performance posture.

Schema versioning and change management

Every time an endpoint's schema loads, Brightspot records a GraphQLSchemaVersion—the full SDL, a hash, the release, and a timestamp. This gives you an automatic, queryable history of your API's shape. Build your change process on it:

• Review diffs on every release. The built-in schema diff tool (under the CMS developer tools) renders a side-by-side comparison of any two recorded versions. Schema changes you didn't intend—from a refactored content type, a new modification, an upgraded plugin—show up here before consumers find them.
• Treat the SDL as a release artifact. The recorded hash makes "did the schema change?" a one-line check in CI or smoke tests.
• Know your breaking changes. Additions are safe. Removals, renames, return-type changes, and shape-changing settings (group-by, modification inlining, type-specific entry fields) are breaking—plan them like any API deprecation: announce, dual-run, migrate consumers (verified via analytics), then remove.

Deployment

• Schemas build at runtime. Endpoints construct their schema from the live database environment and reload when it refreshes or relevant classes change. After a deploy, the first request may pay schema-build cost; for very large schemas, monitor load time (enable profileSchemaLoad() temporarily if it regresses).
• Editorial endpoints are content. Editorially configured endpoints, API clients/keys, REST mappings, and persisted-query registries live in the database—account for them in environment promotion the same way you do other editorial configuration.
• Configuration parity across environments. Keep security posture (introspection, verbose errors, access options) consistent between staging and production so problems surface before release. The only intentional difference should be credentials and origins.

Caching and CDN integration

• GraphQL POSTs don't CDN-cache; persisted queries over GET restore cacheability for read traffic.
• The pageInfo.lastUpdate value (the newest update timestamp among results) is a cheap cache-validation signal for clients.
• REST mappings give selected read paths conventional URLs, making standard HTTP caching strategies trivially applicable to those routes.

Performance posture

A production endpoint should have all four cost-control layers configured (details in Security):

1. Query timeout — converts pathological queries into fast errors.
2. Maximum depth — rejects degenerate nesting outright.
3. Static complexity budget — rejects expensive shapes before execution.
4. Dynamic complexity budget — stops runaway data volumes mid-flight.

Then verify with reality: use analytics to observe actual consumption and @debug profiling on the heaviest queries.

Monitoring

• Usage — endpoint analytics per client, watched for spikes and for retired-endpoint traffic.
• Errors — server logs carry full detail (keep client errors terse); alert on error-rate changes per endpoint.
• Schema — alert when the schema hash changes outside a planned release, and on schema load failures (an endpoint with a failed load can't serve).
• Latency — the standard HTTP-level monitoring of your servlet tier applies unchanged; GraphQL adds no special requirement beyond watching the slow tail, which complexity budgets should keep bounded.

Disaster recovery and resilience

GraphQL endpoints are stateless beyond the database: schemas rebuild from the environment, persisted queries and API clients are records like any other content. Standard Brightspot backup/restore covers them. After a restore, schemas rebuild on first use; no GraphQL-specific recovery steps exist.

Next steps

• Security — the production checklist
• GCA Best Practices — schema design and API-shape guidance