For Connect customers, integration with the Connect API is typically done using a programming language such as javascript/python/etc, but for the purposes of this documentation, we will be using browser extension to demonstrate basic workflows.
For Apollo Studio instructions for both active customers and prospective customers, use this help center article.
Note: API access requires a Noda account. If you do not have one, contact your Customer Success Manager or the contact internal to your company who sent you our way.
Getting set up with a web IDE for managing GraphQL operations
Install Altair
Option A) Add the Altair Chrome Extension to your browser.
Option B) Download and install Altair GraphQL client
Within Altair, enter the API endpoint for the environment that you are accessing. Below is the endpoint for production Connect:
Make sure POST method is selected.
Authenticate with a Collection
Making calls to the Noda Connect API requires a user to be authenticated.
We do this by using a collection and adding some configuration in Altair which will allow for automatic user authentication.
A collection is a group of requests that serves the purpose of providing example queries, organizing a workspace, collaborating with teammates and automating request runs.
Download the attached collection (see end of article).
Open Altair and expand the collections pane by clicking on Collections at the bottom left of the screen.
Import a collection by clicking Import. This will open a file explorer where you will select and open the energy_base_altair_collection.agc file.
Verify that the collection successfully imported. The collection will now be in Altair (as shown). There are some sample queries included in the collection.
In the top right corner of Altair, click on Environments to add an environment where your username and password will be stored.
Add an environment and name it ‘Connect AI’.
Fill in your EMAIL and PASSWORD and hit Save. These are the same credentials that are used to log into Noda.
Now that you’ve created a Connect AI environment, set it as your current environment.
Select a query from the Connect Altair Collection. In this example the Buildings query has been selected.
Click on Pre-request and then click the Enable pre-request script checkbox. This will automatically fetch authentication tokens and include them in your environment prior to the execution of the buildings query.
Select send query.
If your organization has purchased Connect with MFA, then you will receive a prompt to verify your identity.
Note for MFA users: If there is no response returned, do not attempt to re-run the query. Instead, check for the MFA on your device. Multiple failed query attempts can result in a locked out account.
Troubleshooting Authentication: Authentication errors can be caused by several factors. If you are encountering errors, ensure that your query is saved to the Connect Altair Collection.
Leveraging the Schema Documentation
The API documentation for Connect is made available through the docs on the right-hand side of Altair. The docs tab is a powerful tool for exploring the Connect ‘graph’ to understand the types of queries and mutations that are available, as well as to help build queries/ mutations. Select either Query or Mutation to expand the docs.
Click into a query to reveal the arguments, type, and fields. Click into the fields to reveal more of the graph or the object type, if it doesn’t have any fields.
You can write queries directly in Altair or build a query by mousing over the query in the docs, and then hitting Add Query. For example, by mousing over Buildings, you can select the add query option to build a query to return all buildings in Connect. By default, all fields for a building will be added to the query. A query is valid when a run query button appears over the query.
To run a query hit Send query.
For more information on querying Connect, see the next article in this Connect API series here: Querying the API.