Aura API Endpoints configuration and Testing in Insomnia

Insomnia is a collaborative open-source API development platform that makes it easy to build high-quality APIs. This article will help you in understanding how to configure Aura API endpoints in Insomnia.

Prerequisites:

• Download and install Insomnia from the official website: https://insomnia.rest/download
• User must have the aura-api role.
• API credentials requested via the account screen in the Aura Admin console 
• Docs for reference: https://neo4j.com/docs/aura/platform/api/specification/

Authentication:

Insomnia currently does not allow setting authentication at the parent level, and there is an ongoing discussion regarding this feature request. For more detailed information, please refer to this GitHub Link

As a result, it is necessary to configure authentication individually for each request, and it is not possible to set it at the Folder level.

Creating a collection

In order to ensure the functionality of all endpoints, obtaining the access token is necessary. To acquire the access token, please follow the steps provided below:

Windows Users

• Launch Insomnia and locate the "+" icon on the left panel.

• Clicking on the "+" icon will generate a new folder. From the dropdown menu located next to the folder name, you have the option to rename it as per your preference.

Mac Users

To create a new collection, on the home screen, click on the "+" next to collections as shown in the screenshot below.

• Create a new folder by selecting the option from the dropdown, as indicated below,

• Give the folder a name

Setting Variables:

Before proceeding with the addition of different requests, it is important to ensure that you have completed the following steps and added the required variables. These variables will be utilized across all requests.

To add variables, follow below instructions:

• Click on the dropdown menu next to the folder name.Select "Environment" from the options provided
  
• A blank pop-up will appear. Add the variables in JSON format as depicted in the screenshot below:
  
• In this example, we are including variables such as base_url, client_id, client_secret, and api_version. These variables will be frequently utilized in our endpoints.

Get access token:

• Click on the folder name and select "New HTTP Request" from the dropdown menu.
• On the right side, fill in the URI as shown below, and add the required authentication fields:
  
• Another parameter necessary for this endpoint is the "grant_type."
• To add the "grant_type" parameter, navigate to the "Form" tab and select "Form URL Encoded" from the dropdown menu.
• Add "grant_type" as illustrated below:
• Now, click on "Send," and you will receive the access token in the response:
  
• Copy the access token and update it in the environment variables. The updated environment variables will resemble the following:
• Please ensure that whenever you encounter an access token error, you obtain a new access token and update it in the environment variables accordingly.

Example:

Get Instances:

This endpoint returns a list containing a summary of each of your Aura instances.

API Endpoint: {{base_url}}/{{api_version}}/instances
Method: GET 

Configuration:

• Click on the folder name and select "New HTTP Request" from the dropdown menu.
• Fill in the URI as {{base_url}}/{{api_version}}/instances and choose the GET method.
• Navigate to the Auth section and select "Bearer." Ensure that you provide the access token variable and click on SEND.

Upon successful execution, a response code of 200 will be received, and the result will be displayed as follows: