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,81 @@
+= Deploy and operate
+
+== Deploy a GraphQL API
+
+
+Before you deploy a GraphQL API, complete the steps in xref::/aura-graphql-data-apis/prerequisites.adoc[Prerequisites].
+Make sure 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 xref::/aura-graphql-data-apis/authentication-providers.adoc[Authentication providers].
+====
+
+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 its 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 apply, 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.
+To learn more, see xref::/aura-graphql-data-apis/authentication-providers.adoc[Authentication providers].
+
+== Deleting a GraphQL API
+
+When you no longer require the GraphQL API then delete it by using the Aura CLI delete command.
+This requires the Aura instance ID and the 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
+----
+
+[CAUTION]
+====
+There is no additional confirmation - the GraphQL API will start to be deleted as soon as you execute the command.
+====

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

@@ -0,0 +1,16 @@
+= GraphQL for Neo4j AuraDB Beta
+
+Welcome to the beta release of GraphQL for Neo4j AuraDB.
+
+Your feedback and insights help us refine and evolve the product and meet the needs of our users.
+
+The beta release is designed to give you a first look at GraphQL for Neo4j AuraDB.
+You may encounter suboptimal behavior.
+
+You can help us get GraphQL for Neo4j AuraDB ready for production:
+
+- *Dive in*: Explore and test its features.
+- *Test the product limits*: We'd rather discover weak areas at this stage.
+- *Share your experience*: Tell us what works, what doesn't, and what you'd like to see in the future.
+- *Provide feedback*: Use email (`[email protected]`), our `#graphql` channel on our link:https://discord.gg/M8mTADEJ[Discord Community], or our link:https://community.neo4j.com/c/drivers-stacks/graphql/33[forums] to report issues, suggest improvements, or ask questions.
+