Add data api docs

modules/ROOT/content-nav.adoc

@@ -59,6 +59,12 @@
 
 * *Products*
 
+* xref:aura-graphql-data-apis/index.adoc[]
+** xref:aura-graphql-data-apis/prerequisites.adoc[]
+** xref:aura-graphql-data-apis/deploy-and-operate.adoc[]
+** xref:aura-graphql-data-apis/authentication-providers.adoc[]
+** xref:aura-graphql-data-apis/using-your-api.adoc[]
+
 * xref:introspector.adoc[Introspector]
 
 * xref:ogm/index.adoc[]

modules/ROOT/pages/aura-graphql-data-apis/authentication-providers.adoc

@@ -0,0 +1,84 @@
+[[auth-providers]]
+= Authentication Providers
+
+GraphQL for Neo4j AuraDB allows you to use an API key, JWT token from an external identity provider or both for authentication and switch between them as needed. The authentication method is stored as an authentication provider.
+
+There are advantages and disadvantages of both types. API keys are quick to start working with but do not allow for access controls and should not be used within a user facing-client application. JWKS (JSON Web Key Sets) authentication providers require an external identity provider but do allow for fine grained rules around authentication/authorization.
+
+[NOTE]
+====
+`--data-api-id` is used with the `aura-cli` when working with authentication providers rather than `--graphql-api-id` as you might have expected. Conceptually a GraphQL API is a type of Data API and there may be other types in the future. Using `--data-api-id` allows for flexibility for potential future development work in this area.
+====
+
+== Create a JWKS Authentication Provider
+
+Before using JWKS authentication providers, it is necessary to set up and configure an identity provider that manages users and their credentials securely, issues JWTs to authenticated users, and hosts a JWKS endpoint that is can be used to validate JWTs by the GraphQL API. There are several 3rd parties who provide this type of service, e.g Ping, Okta, Auth0 and any of the main cloud service providers. Configuration of identity providers is beyond the scope of this guide.
+
+If you do use a JWKS authentication provider, then you can take advantage of fine-grained access controls using the ** xref:security/authentication.adoc[`@authentication`]/** xref:security/authorization.adoc[`@authorization`] directives of Graphql for Neo4j AuraDB.
+
+[NOTE]
+====
+If you do make use of `@authentication`/`@authorization` rules, they will also be applied to requests made with API keys. We do not currently support adding claims to API keys so it is unlikely they will be able to meet the rules you specify.
+====
+
+The aura-cli is used to create a new JWKS authentication provider. You will need the JWKS URL to do this along with the ID of the GraphQL API with it’s associated AuraDB ID.
+
+At a command prompt, type the following, swapping out the UPPERCASE values for your own:
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql auth-provider create --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --name AUTH_PROVIDER_FRIENDLY_NAME --type jwks --url JWKS_URL
+----
+
+On success, the command will respond with details about the newly created JWKS provider.
+
+== Create an API Key Authentication Provider
+
+[WARNING]
+====
+If you use an API key authentication provider in a user-facing client application, you risk leaking the API key to your users. This could potential give them full access to your GraphQL API. For these usecases, we recommend using JWKS authentication providers.
+====
+
+When a new GraphQL API is created via the aura-cli, an API Key authentication provider is the default. However, if you require a new one, this command allows you to create a new API Key.
+
+At a command prompt, type the following, swapping out the UPPERCASE values for your own:
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql auth-provider create --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --name AUTH_PROVIDER_FRIENDLY_NAME --type api-key
+----
+
+On success, the command will respond with details about the newly created API Key.
+
+[NOTE]
+====
+Make sure to record the API key shown in the response as it will not be displayed again.
+====
+
+== List Authentication Providers
+
+To see the list of authentication providers for a given GraphQL API use the following, exchanging UPPERCASE values for your own.
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql auth-provider list --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID
+----
+
+== Delete an Authentication Provider
+
+An authentication provider for a GraphQL API can be removed by deleting it. At least one enabled authentication provider is required for a GraphQL API.
+
+. Find the API authentication provider ID
++
+[source, bash, indent=0]
+----
+aura-cli data-api graphql auth-provider list --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID --output table
+----
++
+. From the table, locate ID for the authentication provider that you wish to delete
+. Delete the API key provider with this aura-cli statement
++
+[source, bash, indent=0]
+----
+aura-cli data-api graphql auth-provider delete AUTH-PROVIDER-ID --data-api-id YOUR_GRAPHQL_DATA_API_ID --instance-id YOUR_AURA_INSTANCE_ID
+----

modules/ROOT/pages/aura-graphql-data-apis/deploy-and-operate.adoc

@@ -0,0 +1,73 @@
+= Deploy and Operate
+
+== Deploy a GraphQL API
+
+
+Deploying a GraphQL API requires you first to have completed the steps in xref::/aura-graphql-data-apis/prerequisites.adoc[Prerequisites]. Of particular importance is that you have:
+
+* The ID, username and password for the AuraDB
+* A file containing the type definitions
+
+You are now ready to create the GraphQL API with the Aura CLI. Substitute the values in `CAPITALS` to match your setup:
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql create --name YOUR_FRIENDLY_NAME --instance-id YOUR_AURA_INSTANCE_ID --instance-username YOUR_AURA_INSTANCE_USER --instance-password YOUR_AURA_INSTANCE_PASSWORD --type-definitions-file
+FULL_PATH_TO_YOUR_TYPE_DEFS --await
+----
+
+[NOTE]
+====
+Make sure to record the API key shown in the response as it will not be displayed again. If the API key is lost, a new one can be created by following the steps to create a new API key auth provider in the xref::/aura-graphql-data-apis/authentication-providers.adoc[authentication provider] section
+====
+
+There are other items of note in the response:
+
+* `id`: unique identifier for the GraphQL API
+* `status`: tells you if the GraphQL API is ready to receive requests
+* `url`: the connection address to access the GraphQL API
+
+To check if the GraphQL API is ready for requests, use the Aura CLI again, changing `YOUR_AURA_INSTANCE_ID` for the ID of your aura instance.
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql list --instance-id YOUR_AURA_INSTANCE_ID
+----
+
+When the status changes to `ready`, the GraphQL API is available for servicing requests.
+
+== Modifying an Existing GraphQL API
+
+It is possible to change the configuration of an existing GraphQL API. The following properties can be modified:
+
+* Friendly name of the GraphQL API
+* Username and/or password for the associated Aura instance
+* Type definitions
+
+To do this, use the Aura CLI update command which requires IDs of the GraphQL API and it’s linked AuraDB instance. The format of this Aura CLI command is as follows:
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql update YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID <flags>
+----
+
+As the change takes a few moments to fully implement, you should check the status of the GraphQL API after performing this operation; if the status is `updating` then the change is still being processed. When the change is committed, the status will return to `ready`.
+
+
+Additionally, it is possible to modify the authentication providers of GraphQL APIs. More on what these are and how to do this xref::/aura-graphql-data-apis/authentication-providers.adoc[here].
+
+== Deleting a GraphQL API
+
+When you no longer require the GraphQL API then delete it by using the Aura CLI delete command. This will require the Aura instance ID and ID of the GraphQL API.
+
+The format of this command is as follows:
+
+[source, bash, indent=0]
+----
+aura-cli data-api graphql delete YOUR_GRAPHQL_API_ID --instance-id YOUR_AURA_INSTANCE_ID
+----
+
+[NOTE]
+====
+There is no additional confirmation - the GraphQL API will start to be deleted as soon as you press the Enter key!
+====

modules/ROOT/pages/aura-graphql-data-apis/index.adoc

@@ -0,0 +1,23 @@
+= GraphQL for Neo4j AuraDB Beta
+
+== Foreword
+
+Welcome to the beta release of *GraphQL for Neo4j AuraDB*.
+
+We are thrilled to have you join us at this exciting stage of our journey. Participating is more than just trying out this feature – your feedback and insights will directly influence how we refine and evolve its future to meet the needs of users like you.
+
+This beta release is designed to give you a first look at *GraphQL for Neo4j AuraDB*. While we’ve worked hard to ensure a functional and valuable experience, there is the chance that you may encounter suboptimal behavior. We see these occasions as chances to listen, learn, and improve before *GraphQL for Neo4j AuraDB* is released to all of our customers.
+
+Here’s how you can help us get *GraphQL for Neo4j AuraDB* ready for production:
+
+- *Dive in*: Explore and test its features to your heart’s content.
+- *Break stuff*: We’d rather discover weak areas at this stage – go for it, don’t hold back.
+- *Share your experience*: Tell us what works, what doesn’t, and what you’d like to see in the future.
+- *Stay in touch*: Use email (`[email protected]`), our `#graphql` channel on our https://discord.gg/M8mTADEJ[Discord Community], or our https://community.neo4j.com/c/drivers-stacks/graphql/33[forums] to report issues, suggest improvements, or ask questions.
+
+We value your time, creativity, and honest feedback – thank you for your trust and collaboration.
+
+Sincerely,
+
+Jonathan Giffard
+The GraphQL Team at Neo4j

modules/ROOT/pages/aura-graphql-data-apis/prerequisites.adoc

@@ -0,0 +1,197 @@
+= Prerequisites
+
+Management of the beta of GraphQL for Neo4j AuraDB is performed using the Aura CLI command line tool which will need to be installed. Future versions of GraphQL for Neo4j AuraDB will be fully integrated with the Aura Console.
+
+== Read This Before You Start
+
+Using the GraphQL API during the Open Beta will be at no cost to you. Usage of the associated AuraDB instance will be charged as normal unless you’re using Aura Pro Trials which, as the name suggests, is a zero-cost option.
+
+At the end of the beta period, all running GraphQL endpoints will be terminated and destroyed in preparation for the full release. Notification of this will be sent out two weeks before GraphQL endpoints are withdrawn.
+
+
+== Obtain Aura API Credentials
+
+The Aura CLI communicates with Neo4j AuraDB platform by use of 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
+
+1. Login into the https://console.neo4j.io/[Neo4j Aura Console]
+2. Navigate to the top right where your account name is displayed as shown in the red box below and click on the down arrow:
++
+image::aura-graphql-data-apis/unified-console-home.png[]
++
+3. From the menu, choose API keys:
++
+image::aura-graphql-data-apis/unified-console-account-dropdown.png[]
++
+4. Select Create:
++
+image::aura-graphql-data-apis/unified-console-api-keys.png[]
++
+5. On the pop-up window, enter a name for the API Key and then select Create:
++
+image::aura-graphql-data-apis/unified-console-create-api-key.png[]
++
+6. You will be shown the client id and client secret. 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
+
+1. Login into the https://console.neo4j.io/[Neo4j Aura Console]
+2. Navigate to the top right where your account name is displayed as shown in the red box below and click on the down arrow:
++
+image::aura-graphql-data-apis/console-classic-home.png[]
++
+3. You will be shown a menu with your account name. Select Account Details
+4. From the Account Details display, select the Create button in the Aura API Credentials section:
++
+image::aura-graphql-data-apis/console-classic-api-keys.png[]
++
+5. On the pop-up window, enter a Client name, and select Create
+6. You will be shown the newly created Client ID and Client Secret. Make sure to securely save these as they are required to use the Aura CLI
+
+== Install & Configure the Aura CLI
+
+=== Installation
+
+. Using your browser, navigate to https://github.com/neo4j/aura-cli/releases/tag/v1.1.0
++
+[NOTE]
+====
+We advise using at least version 1.1.0 for managing your GraphQL APIs
+====
++
+. Download the compressed file that matches your computer. 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
+.. Mac/Linux users:
++
+[source, bash, indent=0]
+----
+sudo mv aura-cli /usr/local/bin
+----
++
+.. Windows users:
++
+[source, cmd, indent=0]
+----
+move aura-cli c:\windows\system32
+----
++
+. At the command prompt, type:
++
+[source, bash, indent=0]
+----
+aura-cli -v
+----
++
+. You should see this:
++
+[source, bash, indent=0]
+----
+aura version v1.1.0
+----
+
+[NOTE]
+====
+If you are using a Mac, you may receive a rather alarming warning from Apple that aura-cli could not be verified. If this happens, then open *system settings*, select *Privacy & Security* on the left, and scroll down on the right. Select *Open Anyway*. This should not happen again. The aura-cli has been through the Apple certification process but this 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:
++
+[source, bash, indent=0]
+----
+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:
++
+[source, bash, indent=0]
+----
+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:
++
+[source, bash, indent=0]
+----
+aura-cli config set beta-enabled true
+----
++
+. Check commands are listed for the open beta:
++
+[source, bash, indent=0]
+----
+aura-cli data-api graphql
+----
++
+. You should see this:
++
+[source, bash, indent=0]
+----
+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.
+----
+
+== Author GraphQL Type Definitions
+
+Before you create a GraphQL API for use with an Aura instance, you must have type definitions ready for use.
+
+If you already have type definitions from an existing GraphQL implementation these can be used but some exceptions need to be dealt with as these are not currently supported.
+
+* The `@customResolver`/`@populatedBy` directives
+* Subscriptions
+
+Using the https://graphql-toolbox.neo4j.io/[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.
+
+[NOTE]
+====
+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 https://github.com/neo4j/graphql/releases?q=%40neo4j%2Fgraphql%407.0.0-alpha&expanded=true[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 To Use
+
+At the command prompt, type:
+
+[source, bash, indent=0]
+----
+aura-cli instance list
+----
+
+Your AuraDB instances will be displayed along with their IDs. Make a note of the ID for the AuraDB instance that you will use with the GraphQL API.
+
+After choosing an AuraDB to use and obtaining it’s ID, you must also have its username and password to use for authentication. For AuraDB, the username will likely be neo4j and the password would have been shown when it was created. If you do not have this information you cannot proceed with this instance.