REST Mapping

REST mapping transforms any GraphQL endpoint—GCA, code generator, or framework—into REST-style path-based routes that return plain JSON. The API remains GraphQL-backed under the hood, with all the schema validation, type safety, and unified data fetching that implies, but clients consume it like a traditional REST API: no GraphQL client, no query syntax.

Use it to provide a simpler entry point for consuming Brightspot content, to support consumers with existing REST tooling (webhooks, legacy integrations, simple mobile backends), or as a bridge strategy while a team adopts GraphQL gradually.

How it works

A REST mapping endpoint is an editorially-managed API endpoint that owns:

a path prefix (e.g. /api/content), and
a list of mappings, each pairing a route (path + allowed HTTP methods) with a stored GraphQL query.

When a request arrives, the endpoint matches the path to a mapping, builds GraphQL variables from the request's query string, executes the stored query against the source GraphQL endpoint, and writes the GraphQL response JSON back to the client. The flow per request:

Route match — exact match of the request path against prefix + mapping path. No match → 404; method not allowed for the matched path → 405.
Variable extraction — query string parameters become GraphQL variables (see below).
Execution — the mapped query runs against the source endpoint with those variables.
Response — the standard GraphQL response body (data, plus errors/extensions when present) is returned as JSON. If the response contains errors and no status was set, the status is 400; otherwise 200.

Creating a mapping

The natural starting point is the GraphQL Explorer: write and test the query you want to expose, then use the Explorer's REST mapping action, which carries the query over into the mapping form.

Choose an existing REST endpoint to add the route to, or create a new one (name + path prefix; the prefix defaults to a normalized form of the name, e.g. "Content API" → /content-api).
Confirm the name and path for the route (the path defaults from the name).
Pick the HTTP methods—GET, POST, PUT, DELETE. The form pre-selects based on the query type: queries get GET, mutations get POST.
Save and publish. The route is live at {prefix}{path}.

Each mapping stores the full GraphQL query text—operation name, variables, and all—and the form links back to the Explorer so you can re-run a mapping's query at any time. A REST endpoint always references exactly one source GraphQL endpoint; the mapped queries execute with that endpoint's schema, security, and settings.

Passing variables

Clients supply the query's variables through the request's query string. Two formats are supported, controlled by the endpoint's Disable Parameter Slash Syntax setting (under Advanced):

Slash syntax (default)

Parameter names are slash-delimited paths that build nested variable structures:

1GET /content-api/article?with/_id=0000019b-a37e-ddc0-af9f-b37edded0000

becomes:

1{ "with": { "_id": "0000019b-a37e-ddc0-af9f-b37edded0000" } }

Repeatable parameters (name[]=a&name[]=b) produce lists. This keeps URLs readable and cache-friendly for the common cases.

JSON syntax

With slash syntax disabled, each parameter's value is parsed as a JSON literal:

1GET /content-api/article?with={"_id":"0000019b-a37e-ddc0-af9f-b37edded0000"}

Use this when variables are deeply structured and you'd rather construct them as JSON on the client.

note

GraphQL authentication parameters (apiKey, client ID/secret) are never forwarded as variables—they're reserved for authentication.

Security

Each REST endpoint has its own API Access option. Leave it on Inherit to apply the source GraphQL endpoint's access rules, or override it to give REST consumers a different posture—for example, an implicit-access REST facade over an otherwise key-required GraphQL endpoint, exposing only the specific queries you've mapped.

That last point is the key security property: REST consumers can only execute the queries you've mapped, with only the variables those queries declare. A REST mapping is effectively a hand-picked, allowlisted slice of your GraphQL API—similar in spirit to static persisted queries.

Example: an article-by-id route

Mapping configuration:

Endpoint: name "Content API", prefix /content-api, source: your GCA endpoint.
Mapping: path /article, methods GET, query:

1query GetArticle($with: RecordGetInput!) {
2  Get {
3    Record(with: $with) {
4      State {
5        ... on Article {
6          headline
7          body
8        }
9      }
10    }
11  }
12}

Request and response:

1GET /content-api/article?with/_id=0000019b-a37e-ddc0-af9f-b37edded0000

1{
2  "data": {
3    "Get": {
4      "Record": {
5        "State": {
6          "headline": "Welcome to Brightspot",
7          "body": "Hello world!"
8        }
9      }
10    }
11  }
12}

Standard HTTP caching applies to GET routes, making CDN integration straightforward for read-heavy delivery.

When to prefer real GraphQL

REST mapping trades flexibility for simplicity: each route returns a fixed shape, and adding a field means editing the mapping. When a consumer starts needing many routes or per-request field selection, that's the signal to move them to the GraphQL endpoint directly—conveniently, they're already running on one.

Next steps

GraphQL Explorer — author and test mapped queries
Persisted Queries — the GraphQL-native allowlisting alternative
Security — API access options in depth

How it works​

Creating a mapping​

Passing variables​

Slash syntax (default)​

JSON syntax​

Security​

Example: an article-by-id route​

When to prefer real GraphQL​

Next steps​