Overview of GraphQL

There are two API endpoints supported: Content Delivery API and Content Management API.

The Content Delivery API is most appropriate when you want to use Brightspot as a headless CMS. It leverages the Brightspot View System to deliver content in a form most suitable for rendering a web page or powering a mobile app.

The Content Management API is useful if you wish to programmatically query, save, and delete content in Brightspot from another application. This is a lower level API that offers similar functionality as the Dari Java APIs for querying and persistence.

For both APIs, their respective GraphQL schemas are auto-generated based on the view models (Java classes extending ViewModel) and data models (Java classes implementing Recordable) that are present in your application. That is to say, the GraphQL schema will always accurately reflect your current application model, and there is no code or configuration needed to keep the two in sync.

Basic API Information

All requests to the API must be made using the HTTP POST method. The request body should be a JSON payload with corresponding Content-Type Header set to application/json. The JSON object should contain a query key with a valid GraphQL query string as its value. Optionally, the object can contain a variables key and a map of key/value pairs as its value if you wish to pass dynamic arguments to the query. The response will also be a JSON payload formatted to the GraphQL specification.

Authentication

An API key is required for all requests made to the Content Management API. The key can either be passed as a query parameter in the URL named api_key or as a Header with the name X-API-Key. Your API key identifies you and your app as the consumer of the API, and it is important to keep it secret and safe to prevent unauthorized access to your content. As such, client-side requests even under SSL would be considered insecure since the visitor to your site could easily view the outgoing requests from their browser.

To obtain an API key, you or an administrator of your Brightspot instance must do the following:

  1. From the Brightspot navigation menu, select Admin > APIs.

  2. In the Clients widget, click Create New Client. A New API Client form appears.

    ../../../_images/new-api-client.png
  3. In the Name field, add a descriptive name to identify your application.

  4. In the Keys field, click Add API Key. A new form appears revealing your API key.

    ../../../_images/new-api-key.png

    Attention

    Copy the key and store it in safe place. After the form is submitted you will NOT be able to see the API key again.

  5. You can also give the generated key a descriptive Name to help you identify it later on.

  6. Click Save.

Brightspot activates your API Key, and saves any associated configurations to it.

Debugging

As you are building out your application, you will want to explore the API methods available and run test queries against them. Rather than obtaining an API Key and hitting the actual API endpoint, you can instead use the developer tools right from within Brightspot. The tool can be accessed by navigating to Developer > GraphQL from the Brightspot navigation menu. From there, select from the drop-down the API endpoint you wish to explore and test.

../../../_images/graphql-debugger-ui.svg

Be mindful too of your user’s current Site as denoted in the top right corner of the CMS, as that will dictate the set of content that can be returned from your sample queries. After choosing an endpoint you will be presented with an interactive GraphQL IDE called GraphiQL configured to hit that endpoint. From there you can explore the API using the Documentation Explorer, run queries, and view a history of past queries that you’ve run. Queries executed through this tool are not tracked against an API Key.