Aura Query API tutorial

modules/ROOT/content-nav.adoc

@@ -122,6 +122,10 @@ Generic Start
 ** xref:api/overview.adoc[]
 ** xref:api/authentication.adoc[]
 ** link:{neo4j-docs-base-uri}/aura/platform/api/specification/[API Specification]
+
+* Tutorials
+** xref:tutorials/aura-query-api-tutorial.adoc[Query API on Aura]
+
 ////
 AuraDB End
 ////

modules/ROOT/pages/tutorials/aura-query-api-tutorial.adoc

@@ -0,0 +1,91 @@
+[[aura-query-api-tutorial]]
+= Aura Query API
+:description: This page describes how to create a node using Query API and an Aura instance.
+
+== Introduction
+
+The Query API enables interaction with an Aura database using Cypher via HTTPS.
+
+This tutorial guides you through the process of sending Cypher queries to an Aura instance using the Query API.
+
+For more information, see the link:https://neo4j.com/docs/query-api/current/[Query API documentation] but note that:
+
+* For Aura instances, the host follows the format `<databaseID>.databases.neo4j.io`
+
+* The Query API documentation mainly refers to self-managed instances that use port `7474`, whereas Aura supports HTTPS only, which defaults to port `443` 
+
+* As HTTPS implies port `443` in the request, you do not need to include the port in the URL.
+
+== API endpoint
+
+To send Cypher queries to an Aura instance, make a `POST` request to the following API endpoint:
+
+[source, header]
+----
+https://<instanceID>.databases.neo4j.io/db/<databaseName>/query/v2
+----
+
+*Parameters*
+
+`<databaseID>` = The unique ID of your Aura database (e.g. e011c23c).
+
+`<databaseName>` = The target database (use `neo4j` for the default database).
+
+*Example Endpoint:*
+
+[source, header]
+----
+https://537dfda7.databases.neo4j.io/db/neo4j/query/v2
+----
+
+aura recently introduced custom endpoint... i.e. a alias that points to #####.databases.neo4j.io
+
+=== Custom endpoints
+
+You can send Cypher queries to the Query API using a custom endpoint just as you would with the standard one.
+
+https://<customerEndpoint>.endpoints.neo4j.io:443/db/neo4j/query/v2
+
+`<customerEndpoint>` = The target endpoint 
+
+https://technology3ndpoint-dev-eng.endpoints.neo4j.io:443/db/neo4j/query/v2
+
+== Queries using cURL
+
+You can interact with the Query API using cURL, in your command-line terminal. 
+This provides a simple way to communicate with the database without using a language library. 
+Ensure that cURL is installed in your system before proceeding.
+
+== Example: create a node 
+
+This example demonstrates how to create a Person node in an Aura instance, using cURL:
+
+[source, shell]
+----
+curl -vvv -X POST \ # <1>
+   -H "Authorization: Basic bmVvNGo1MlFidnE4TEFrRnZwXzdjT1NRM2F1NTJXVVRpTXotUERXQTU1NTdmRWFKdw==" \ # <2>
+   -H "Content-Type: application/json" \ # <3>
+   -d '{ "statement": "CREATE (n:Person {name: \'Alice\'\}) RETURN n" }' \ # <4>
+   https://537dfda7.databases.neo4j.io/db/neo4j/query/v2 # <5>
+----
+
+=== Explanation
+
+<1> `-X POST` Specifies that the request is a POST request.
+
+<2> `-H "Authorization: Basic <base64_encoded_credentials>":` Replace <base64_encoded_credentials> with your Base64-encoded Neo4j credentials (neo4j:your-password).
+Learn more about link:https://neo4j.com/docs/query-api/current/authentication-authorization/#_basic_authentication[basic authentication].
+
+<3> `-H "Content-Type: application/json"` Specifies that the request body is in JSON format.
+
+<4> `-d '{ "statement": "CREATE (n:Person) RETURN n" }'` Contains the Cypher query to create a Person node.
+
+Note: The `\` backslashes allow multi-line commands in the terminal.
+
+== Tip
+
+You can also use tools like Postman to format and send requests more easily.
+
+== Next Steps
+
+Try executing different Cypher queries to retrieve, update, or delete nodes in your Aura database.