Aura API Endpoints configuration and Testing in Windows CMD

The Aura API allows you to programmatically perform actions on your Aura instances without the need to log in to the Console.

A complete list of the available endpoints and actions can be seen and tested in the API Specification.

This article provides the steps for setting up your MS Windows environment (CURL in CMD) for using the Aura API endpoints.

Prerequisites

• The user must have the aura-api role in the Aura Console. Please raise a support ticket with us to get this role associated with your user.
• API credentials requested via the account screen in the Aura Admin console 
• Docs for reference: Aura API documentation
• Windows has CURL built in since 2018. Run 'curl -V' in CMD(command prompt) to verify curl's availability in your machine.

Caveats in Windows:

• Use double quotes instead of single quotes.
• Use the ^ (Caret) operator to mark line continuations (Command extends to the next line)
• Use -k or –insecure flags in curl to skip SSL verification.
• CMD becomes cumbersome for API requests with a multi-line request body. We recommend using single-line versions.

Debug logs / verbose:

Steps:

• Save the Client ID and Client Secret as Environmental variables.
• Fetch and save the Bearer Token as a local variable.
• token has expired

Querying the Aura API Endpoint:

• Tenant Level:
  • List all tenants
  • Get a tenant's details
• Instance Level:
  • Read instances:
    • List all instances
    • Get an instance's details
  • Modifying instances:
    • Create a new instance
    • Pause an instance
    • Resume a paused instance
    • Delete an instance

This is just a small set of examples.
Refer to the API Specification document to get the complete list of the available endpoints and actions.

Save the Client ID and Client Secret as Environmental variables:

1. Create a Client ID and Client Secret for your user account from the 'Account Details' page in the Aura Console.
   
   
2. Save them as separate user or system Environment Variables:
   The names of the variables can be anything as long as :
   1. They are unique in your system
   2. You can remember them for reuse in the later steps\
      

For this demonstration, we will be using the variable names AURA_API_CLIENT_ID and AURA_API_CLIENT_SECRET

Fetch and save the Bearer Token as a local variable

The Client ID and Client Secret will be used only for the initial authentication to get a bearer token.
All other actions performable will need only the bearer token.

The below command:

1. Uses the AURA_API_CLIENT_ID and AURA_API_CLIENT_SECRET variables saved in the previous step and makes a call to the https://api.neo4j.io/oauth/token endpoint
2. Fetches the bearer token
3. Saves it as a local variable called bearer_token

FOR /F "tokens=2 delims=:," %G IN ('curl --insecure --request POST "https://api.neo4j.io/oauth/token" --user "%AURA_API_CLIENT_ID%:%AURA_API_CLIENT_SECRET%" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "grant_type=client_credentials" ^| find "access_token"') DO set bearer_token=%G

Verification:

echo %bearer_token%

error: key not authorized: token has expired

The bearer token, once fetched, will be valid for 1 hour. If it expires, rerun the above command to get a new token and save it.

Tenant Level actions:

List all tenants:

Endpoint: https://api.neo4j.io/v1beta3/tenants (GET)

curl --insecure --request GET "https://api.neo4j.io/v1beta3/tenants" ^
--header "accept: application/json" ^
--header "Authorization: Bearer %bearer_token%"

Get a tenant's details:

Endpoint: https://api.neo4j.io/v1beta3/tenants/{tenant-id} (GET)
This can be used to find the instance sizes, regions, types (AuraDB/AuraDS) and Tier (professional /enterprise) enabled for your tenant.

The tenant id can be found in the previous call's (https://api.neo4j.io/v1beta3/tenants) output.

curl --insecure --request GET "https://api.neo4j.io/v1beta3/tenants/{tenant-id}" 

Example:

curl --insecure --request GET "https://api.neo4j.io/v1beta3/tenants/2cebed51-xxxx-xxxx-xxxx-xxxxxx" ^
--header "accept: application/json" ^
--header "Authorization: Bearer %bearer_token%"

Instance Level actions:

Read instances:

List all instances :

Endpoint: https://api.neo4j.io/v1beta3/instances (GET)

curl --insecure --request GET "https://api.neo4j.io/v1beta3/instances" ^
--header "accept: application/json" ^
--header "Authorization: Bearer %bearer_token%" 

If you have multiple tenants, the result will include the details of all active instances from all your tenants.

Get an instance's details:

Endpoint: https://api.neo4j.io/v1beta3/instances/{instanceId} (GET)
The instance id can be found using the https://api.neo4j.io/v1beta3/instances endpoint or from the Aura Console - What is my DB ID, and how do I retrieve it?

Example:

curl --insecure --request GET "https://api.neo4j.io/v1beta3/instances/35f42614" ^
--header "accept: application/json" ^
--header "Authorization: Bearer %bearer_token%" 

Modifying instances

Create a new instance:

Endpoint: https://api.neo4j.io/v1beta3/instances (POST)
Request Body:

{
"version": "<Neo4j major version>",
"region": "<CSP region name>",
"memory": "<Instance's memory>",
"name": "<Friendly instance name>",
"type": "<Instance tier and type>",
"tenant_id": "<YOUR_TENANT_ID>"
}

Version: '4' or '5'
RegioThis should be a region that has been enabled for your tenant. Please take a look at the output of Get a tenant's details.
Memory: '4GB', '8GB', etc.
Name: Your preferred name for the instance. does not have to be unique
Type: Should be based on your tenant's allowed Type (AuraDS/AuraDB) and Tier. Refer to Get a tenant's details
tenant_id: Your tenant ID.

Example:
 The below request will create a

• Neo4j 4 version 
• AuraDB Enterprise Tier (enterprise-db) instance
• In the eastus (Azure) region
• With 4GB RAM
• Named 'Aura_API_demo_2'
• In the tenant '2cebed51-xxxx-xxxx-xxxx-xxxxxxxx'

curl --insecure -s -X POST "https://api.neo4j.io/v1beta3/instances" ^
-H "accept: application/json" ^
-H "Authorization: Bearer %bearer_token%" ^
-H "Content-Type: application/json" -d "{\"version\": \"4\",\"region\": \"eastus\",\"memory\": \"4GB\",\"name\": \"Aura_API_demo_2\",\"type\": \"enterprise-db\",\"tenant_id\": \"2cebed51-xxxx-xxxx-xxxx-xxxxxxxx\"}"

The response will contain the new instance's:

• Connection_url
• DBID
• Username (neo4j)
• The default password for the neo4j user
  

Pause an instance:

Endpoint: https://api.neo4j.io/v1beta3/instances/{instance_id}/pause (POST)
Example: (Pause the instance with DBID c5606163)

curl --insecure -s -X POST "https://api.neo4j.io/v1beta3/instances/c5606163/pause" ^
-H "accept: application/json" ^
-H "Authorization: Bearer %bearer_token%"

Resume a paused instance:

Endpoint: https://api.neo4j.io/v1beta3/instances/{instance_id}/pause (POST)
Example: (Resume the instance with DBID c5606163)

curl --insecure -s -X POST "https://api.neo4j.io/v1beta3/instances/c5606163/resume" ^
-H "accept: application/json" ^
-H "Authorization: Bearer %bearer_token%"

Delete an instance

Endpoint: https://api.neo4j.io/v1beta3/instances/{instance_id} (DELETE)
Example: (Delete the instance with DBID c5606163)

curl --insecure -s -X DELETE "https://api.neo4j.io/v1beta3/instances/c5606163" ^
-H "accept: application/json" ^
-H "Authorization: Bearer %bearer_token%"

You will get an empty response body for successful Pause, Resume and Delete actions.
Additional details will be displayed only on failure.
As mentioned earlier, you can use the --verbose flag to get more details in the response.