How to: Use the GraphQL Sandbox

Overview

Each environment comes with its own GraphQL sandbox for requesting environment audit and event logs. Accessing this sandbox requires modifying your environment URL to the following: https://{unqorkEnv}/api/graphql, where {unqorkEnv} is the name of your environment. Once accessed, you can authenticate the sandbox using the environment's unqorkioToken cookie.

In production environments, the GraphQL sandbox is not available for access by browser. Instead, use the curl command that displays on the GraphQL page to query the endpoint.

What You'll Learn

In this article, you'll learn how to retrieve the cookie, authenticate the sandbox, and begin requesting data.

Locating the Authentication Token

To use your environment's GraphQL sandbox, you first need to find your environment's unqorkio authentication token:

1. Log in to your environment on the Unqork Designer Platform.
2. Right mouse-click anywhere on your Workspaces page.
3. Click Inspect. DevTools open as a panel on the right side of your page.

If you’re using a Mac, Command + Option + i also opens the DevTools.

4. At the top of the panel, select the Application tab.
5. In the menu to the left, find the Storage section.
6. Under Cookies, select the environment web page address. For example, https://test.unqork.io.
7. In the right panel, find and select the unqorkioToken key.
8. At the bottom of the panel, copy the unqorkioToken cookie value.

A static image displaying the Unqork token you must obtain in your environment's DevTools Console to authenticate the GraphQL sandbox.

Accessing the Environment API GraphQL Sandbox

To access your environment's API GraphQL sandbox:

1. Open a new browser page.
2. In the browser bar, insert https://{unqorkEnv}/api/graphql, where {unqorkEnv} is the name of your environment. For example: https://training.unqork.io/api/graphql.
3. Press Enter (Return). The GraphQL for the specified environment loads.

An authentication token is required to perform queries or mutations. On initial page load, the "Unable to reach server" modal displays. Next, you need to authenticate your GraphQL sandbox to request logs.

Authenticating the GraphQL Sandbox

Authenticate access to the environment by inserting your unqorkio token into HTTP Headers, this is required to perform any function in the GraphQL.

To authentic access to your environment:

1. At the bottom left of the GraphQL editor, click Headers.
2. In the Header Key field, enter unqork-auth-token. No quotes necessary.
3. In the Value field, paste the cookie value you obtained in the Locating the Authentication Token section of this article. No quotes necessary.

A static image displaying the necessary Headers and Unqork token to authenticate the GraphQL sandbox in your environment.

Successful authentication is denoted by the error message modals clearing from the Response panel. You can now create queries or mutations for your environment.

Performing API Calls

You can use your environment's GraphQL sandbox to perform queries A query lets you retrieve, access, manipulate, and delete data in a database. and mutations. The GraphQL sandbox comes with preconfigured Root Types Root Types are the operations you can perform in the GraphQL sandbox. In GraphQL, Root Types can be queries, mutations, or subscriptions. so you can quickly set up for API calls. After selecting the query or mutation you want to perform, you'll specify the parameters and run the call.

In Unqork, you'll use the GraphQL sandbox for the following features:

  • Performing queries on audit logs.

  • Performing queries and mutations on Application Versioning.

To learn more about audit logs, view our Audit Logs Reference Guides. To learn more about Application Versioning, view our Application Versioning article.

Querying Audit Logs

You can use the GraphQL sandbox to query audit logs for a specific one-hour range. Depending on the events that occurred in the requested time span, the API call might return data specific to environment logins, password changes, or administration modifications. Remember, you must authenticate the sandbox before proceeding.

To learn how to authenticate and access the environment GraphQL sandbox, see the How to: Use the GraphQL Environment.

To query audit logs:

1. In the Editor panel, remove the example query.
2. In the side panel to the left of the Editor panel, click (Explorer).
3. Under Root Types, select query.
4. Select instrumentation.
5. Select auditlogs.
6. Select listAuditLogs.
7. Select all Arguments and Fields.

As you make your selections, you'll see parameters automatically display in the Variables panel. Next, you'll use this panel to specify the start and end time, schema version, and log location for the audit logs you want to query.

To query audit logs for a specific one-hour range, follow these steps to manipulate the parameters in the Variables panel:

1. For the "startDateTime" key, replace the null value with the date and time you want start querying audit logs. You must use the YYYY-MM-DDThh:mm:ssZ format, where the YYYY is year, MM is the month, DD is the day, hh is the hour, mm is the minutes, and ss is the seconds.

Ensure the seconds (ss) are 00 or are fully omitted to avoid errors.

2. For the "endDateTime" key, replace the null value with the date and time you want end the query. You must use the YYYY-MM-DDThh:mm:ssZ format, where the YYYY is year, MM is the month, DD is the day, hh is the hour, mm is the minutes, and ss is the seconds.

You can only run queries for a one-hour range. For example, "2022-12-19T19:00:00Z" to "2022-12-19T20:00:00Z".

3. For the "schemaVersion" key, replace the null value with "1.0".
4. Click Query. A successful query returns as a URL array in the Response panel.

A static imaging displaying the configured variables and the response after clicking the Query button.

The response lasts 15 minutes before you need to perform another query.

5. Hover over one of the files and click Follow Link. The file automatically downloads to your computer.

A static image displaying the Follow Link option that displays when hovering over a set of audit logs in the Response panel.

6. Using your computer's text editor, open the file from your Downloads folder.
7. Use a JSON beautification tool to format the returned data for easier legibility. For example: https://jsonformatter.org/.

Querying Application Versions

There are various queries you can run related to Application Versioning. This example highlights how to query all versions for an application.

To learn more about Application Versioning, view our Application Versioning article. To learn more about all the Application Versioning queries you can perform, view our Application Versioning: API Reference guide.

To query all version for an application:

1. In the Editor panel, remove the example query.
2. In the side panel to the left of the Editor panel, click (Explorer).
3. Under Root Types, select query.
4. Select administration.
5. Select application.
6. Select getApplicationVersionsBatch.
7. Under Arguments, select getApplicationVersionsBatchInput.
8. Under Input Fields, select applicationId.

This input is required so you can enter an application ID in the Variables panel.

9. At the top of the Documentation panel, click (back) to return to the previous panel.
10. Under Fields, select applicationId and version.

Selecting these fields will display the application's ID and all versions.

As you make your selections, you'll see parameters automatically display in the Variables panel. Next, you'll use this panel to specify the application whose versions you want to query.

To query versions for a specific application, follow these steps to manipulate the parameters in the Variables panel:

1. Remove the null from the parameters.
2. Enter the application ID of the versioned application whose versions you want to query.
3. Click Query. A successful query displays the application versions in the Response panel.

A static imaging displaying the configured variables and the response after clicking the Query button.

Creating a New Application Version

You can also use the GraphQL sandbox to perform mutations. This example provides steps for creating a new version of an application.

To learn more about Application Versioning, view our Application Versioning article. To learn more about all the Application Versioning mutations you can perform, view our Application Versioning: API Reference guide.

To a new application version:

1. In the Editor panel, remove the example query.
2. In the side panel to the left of the Editor panel, click (Explorer).
3. Under Root Types, select mutation.
4. Select administration.
5. Select application.
6. Select createApplicationVersion.
7. Under Arguments, select applicationVersionInput.
8. Under Fields, select applicationId, description, and version.

This input is required so you can enter an application ID, a description of the changes, and the version number in the Variables panel.

 

 

 

 

As you make your selections, you'll see parameters automatically display in the Variables panel. Next, you'll use this panel to specify the application where you'll create a new version with a description of the changes.

To query versions for a specific application, follow these steps to manipulate the parameters in the Variables panel:

1. Remove the null from the parameters.
2. Create a new object using curly brackets ({}).
3. On a new line, enter "applicationId": "{your-application-ID}", where you'll replace {your-application-ID} with the application ID you where you want to create the new version.
4. On a new line, enter "version": "{new-version-number}", where you'll replace {new-version-number} with the new version number you want to use. For example, 1.1.0 for a minor change.

To learn more about version number best practices, view our Application Versioning article.

5. On a new line, enter "description": "{description-of-changes}", where you'll replace {description-of-changes} with a brief description of the changes that were made to the application. For example, Minor fix to re-establish a broken service..
6. Click Mutation. A successful query displays the new application version number and description in the Response panel.

A static imaging displaying the configured variables and the response after clicking the Mutation button.

Resources