CDA/CMA Migration Guide

Brightspot's legacy GraphQL APIs—the Content Delivery API (CDA) for view-model delivery and the Content Management API (CMA) for content CRUD—are deprecated. The GCA replaces both with a single, more capable endpoint. This guide maps the old concepts to their GCA equivalents and lays out a migration path.

Why migrate

• One API instead of two. Delivery (views) and management (content CRUD) coexist on one endpoint—or on two GCA endpoints with different settings, if you prefer the separation.
• Full feature access. Revisions, previews, workflow, transactions, dry runs, group-by aggregation, and type introspection have no CDA/CMA equivalents.
• Active development. New capabilities land in the GCA.

Concept mapping

CDA/CMA concept	GCA equivalent
CDA view-model endpoint	GCA with entryViewClass(...) registrations and disallowAllStateAccess() for the locked-down delivery posture
CDA singleton/view queries	Standalone view models via endpointViewType(...)
CMA per-type query fields	Query/Records(from: ...), or per-type fields via includeTypeSpecificEntryFields()
CMA get-by-id	Get/Record(with: {_id: ...})
CMA save/delete mutations	Content/Action/Save, Delete, plus Publish/Archive/Restore/Workflow
Read/write type configuration	readonlyEntryClass / mutableEntryClass plus contentActionType(...)
API keys / clients	Unchanged—same GraphQLApiAccessOption infrastructure
Persisted queries	Unchanged—see Persisted Queries

Migration path

1. Stand up the GCA endpoint alongside the old one

Create a new GCAEndpoint (or editorial endpoint) on a new path. Nothing about the legacy endpoints changes; you'll migrate consumers gradually.

For a CDA-style delivery endpoint:

1
GCASchemaSettings.newBuilder()
2
    .readonlyEntryClass(Article.class)
3
    .entryViewClass(ArticleViewModel.class)
4
    .disallowAllStateAccess()   // views only, single-object lookups only
5
    .build();

For a CMA-style management endpoint:

1
GCASchemaSettings.newBuilder()
2
    .mutableEntryClasses(Article.class, Author.class)
3
    .contentActionTypesAll()
4
    .includeGetRevision()
5
    .build();

2. Map your queries

The biggest syntactic change is the entry-point structure: the GCA nests operations under Get, Query, View, and Content root fields rather than generating one root field per type. Rewrite queries using the Get, Query, and View documentation as the reference; the GraphQL Explorer makes this quick since both schemas are explorable side by side.

Watch for these differences while translating:

• Predicates are now Dari predicate strings with bound arguments rather than bespoke filter inputs—more expressive, and identical to the Java API.
• Pagination uses offset/limit with a rich pageInfo, replacing any cursor-style pagination your CDA clients used.
• Type names are generated from Java simple names with conflict resolution; verify names in the Explorer rather than assuming they match the old schema.
• View parameters are passed via the Response(typed: ...) / view field arguments rather than CDA's request parameter conventions.

3. Validate parity

• Run representative production queries against both endpoints and diff the results.
• For mutations, use dry runs to validate write behavior without persisting.
• Lean on schema versioning: each schema load is recorded and diffable, so you can track the new endpoint's shape as you tune settings.

4. Move clients, then retire

Migrate one consumer at a time—per-client API keys and analytics tell you exactly who is still calling the legacy endpoints. When traffic reaches zero, remove the old endpoints.

Getting help

If you hit a CDA/CMA capability you can't reproduce on the GCA, check the settings reference first—most legacy behaviors exist as opt-in settings (unique-index-only lookups, visibility filtering, singleton handling). Failing that, contact Brightspot support with the legacy query and the attempted GCA equivalent.