Insomnia Configuration Details

When Insomnia first loads after importing the suite of examples, it will likely be running with no environment selected. Start by clicking on the "No Environment" button to reveal the environment selection drop-down box.

Click "Manage Environments" to load the environment editing interface.

Note that, in the picture, I have already created a "Testing Environment" based on the supplied template. Let's do that now.

Click on the little (+) icon by the "Sub Environments" header and choose to create a "Private Environment". Insomnia will ask whether you want private environments included in any exports, so it is a convenient way to protect your credentials.

Copy and paste the contents of the "Environment TEMPLATE" into your newly created private environment. Replace the contents of the apiKey and apiSecret values with the values provided to you by XOi. We strongly encourage you to limit your testing to the Staging environment, but if you must access the production environment for diagnostics, we recommend that you create a separate private environment for doing so and configure it using the production URLs included in these API docs.

Close the "Manage Environments" dialog and choose your newly created environment from the environment selection drop-down box.

Authenticating to the API in Insomnia

Two examples are provided to demonstrate authentication to the API. "Get Auth Token (json)" POSTs the api key and secret as JSON while "Get Auth Token (basic auth)" uses HTTP basic authentication to do the same.

Because authentication tokens are quite long and must be refreshed on a regular basis, we have set up this example suite to automatically use the token last retrieved via the json request when submitting all other API requests. Be sure to run the "Get Auth Token (json)" request at the start of a testing session and whenever the token expires (every 60 minutes).

Basic vs. Advanced examples

For each query and mutation in the example suite, both a "basic" and "advanced" version has been provided. The basic example demonstrates crafting the GraphQL with any parameters in-line with the rest of the query. These basic examples also tend to request fewer fields to keep the example as tidy as possible.

Advanced examples leverage GraphQL's ability to separate parameters into a separate "Query Variables" structure. These variables can be edited below the query in the Insomnia interface. In a few places, these advanced examples even leverage features in Insomnia that allow requests to refer to the results of a previously run request. For example, the advanced "Retrieve Single Job" request uses the first ID found by the advanced "List Jobs" query as the ID of the job to be retrieved.

Viewing Details

The "Timeline" tab in the output panel is a useful tool for viewing the raw requests being made by Insomnia. You can see the JSON payloads being constructed around the GraphQL queries as well as how headers are being inserted into the requests. If you are not using a pre-packaged GraphQL client, this information can be invaluable as you write code to craft these requests.