Prerequisites

This is the documentation of the GraphQL Library version 6. For the long-term support (LTS) version 5, refer to GraphQL Library version 5 LTS.

The beta of GraphQL for Neo4j AuraDB is managed via the Aura CLI command line tool. You must install and configure the Aura CLI for this purpose. Future versions will be fully integrated with the Aura Console.

Before you start

Using the GraphQL API during the Open Beta is free of charge. Usage of the associated AuraDB instance will be charged as normal unless you’re using Aura Pro Trials which is a zero-cost option.

At the end of the beta period, all running GraphQL endpoints will be terminated in preparation for the full release. We will send out a notification two weeks before they are terminated.

Obtain Aura API credentials

The Aura CLI communicates with Neo4j AuraDB platform via an API. To use the API, a set of credentials is required. To get the credentials, follow these steps depending on which version of the console you are using.

New unified Aura Console experience

Log in to the Neo4j Aura Console.
Navigate to the top right where your account name is displayed and click the down arrow.
In the menu, click API keys.
Click Create.
In the pop-up window, enter a name for the API Key and click Create.
The client ID and client secret are displayed. Make a note as the client secret will not be shown again and you need both. If you download them, keep them safe.

Aura Console classic

Log in to the Neo4j Aura Console.
Navigate to the top right where your account name is displayed and click the down arrow.
A menu with your account name is displayed. Click Account Details.
In the Account Details menu, click Create in the Aura API credentials section.
In the pop-up window, enter a client name and click Create.
The newly created client ID and client secret are displayed. Make sure to securely save these as they are required to use the Aura CLI.

Install and configure the Aura CLI

Installation

Navigate to https://github.com/neo4j/aura-cli/releases/tag/v1.1.0 in your browser.

Use Aura CLI version 1.1.0 or higher for managing your GraphQL APIs.
Download the compressed file that matches your system. Make a note of the folder where the file is located.
After the file has been downloaded, extract the contents.
Open a command prompt and move to the location where you extracted the files.
Complete the installation by moving the aura-cli executable file into the file path.
1. Mac/Linux users:
  sudo mv aura-cli /usr/local/bin
2. Windows users:
  move aura-cli c:\windows\system32
At the command prompt, type:
```
aura-cli -v
```
You should see this:
```
aura version v1.1.0
```

If you are using a Mac, you may receive a warning from Apple that aura-cli could not be verified. If this happens, open System Settings, click Privacy & Security on the left, and scroll down on the right. Click Open Anyway. This should not happen again. The aura-cli has been through the Apple certification process but it can take time to trickle down through the Apple ecosystem.

Add Aura API credentials

Configure the Aura CLI with the Aura API client ID and client secret you obtained earlier. The Aura CLI refers to these as credentials and it is possible to have several sets of credentials and then choose which one to use.

At the command prompt, enter the following, using your values for the items in CAPITALS:

aura-cli credential add --name YOUR_LABEL --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET

To confirm the credentials are working, list your Aura instances:
```
aura-cli instance list --output table
```

Set the beta flag

Instruct the Aura CLI to make available the commands for the open beta. This requires setting a configuration option.

At the command prompt, enter the following:
```
aura-cli config set beta-enabled true
```
Check if the commands are listed for the open beta:
```
aura-cli data-api graphql
```

You should see this:

Allows you to programmatically provision and manage your GraphQL APIs

Usage:
  aura-cli data-api graphql [command]

Available Commands:
  auth-provider Allows you to programmatically manage Authentication providers for a specific GraphQL Data API
  cors-policy   Allows you to manage the Cross-Origin Resource Sharing (CORS) policy for a specific GraphQL Data API
  create        Creates a new GraphQL Data API
  delete        Delete a GraphQL Data API
  get           Get details of a GraphQL Data API
  list          Returns a list of GraphQL Data APIs
  pause         Pause a GraphQL Data API
  resume        Resume a GraphQL Data API
  update        Edit a GraphQL Data API

Flags:
  -h, --help   help for graphql

Global Flags:
      --auth-url string
      --base-url string
      --output string

Use "aura-cli data-api graphql [command] --help" for more information about a command.

Write GraphQL type definitions

Before you create a GraphQL API for use with an Aura instance, you must create type definitions.

If you already have type definitions from an existing GraphQL implementation these can be used. However, you must deal with some exceptions. The following are not currently supported:

The @customResolver and @populatedBy directives
Subscriptions

Using the Neo4j GraphQL Toolbox is an easy way to produce and try out type definitions. Use of the Toolbox requires a connection to your Aura instance.

The Neo4j GraphQL Toolbox currently,supports version 6 of the @neo4j/graphql library. However, GraphQL APIs run the version 7 alpha. As a result, type definitions created via the toolbox may not be valid with a GraphQL API. You can find a list of the breaking changes here.

When your type definitions are ready, save them to a file. They will be used with the Aura CLI to create the GraphQL API.

Select the AuraDB instance

At the command prompt, type:

aura-cli instance list

Your AuraDB instances are displayed along with their IDs. Make a note of the ID of the AuraDB instance that you will use with the GraphQL API.

After choosing an AuraDB to use and obtaining its ID, you must also have its username and password to use for authentication. For AuraDB, the username will likely be "neo4j" and the password has been shown when it was created.