Application Versioning: API Reference

This iteration of the Application Versioning APIs will be deprecated in the 7.10.0 release. For more information about Platform releases, view our 2024 Release Calendar.

Overview

Application Versioning is an important process in software development. Because many team members contribute to the creation of an application, versioning ensures team members are building and testing the correct application version at the correct environment level.

To learn more about Application Versioning, view our Application Versioning article.

This reference guide contains all the necessary API APIs (application programming interfaces) are a set of protocols and definitions developers use to build and integrate application software. APIs act as the connective tissue between products and services. documentation to perform GraphQL queries GraphQL queries perform read operations and let you retrieve and read data. and mutations GraphQL mutations let you create, update, and delete objects and fields in your data. on your versioned applications. For example, you can enable Application Versioning in an application, create application versions, add application dependencies, and so on. To use these APIs, you must access and authenticate your environment's GraphQL sandbox.

To learn about accessing, authenticating, and using the GraphQL sandbox, view our How to: Use the GraphQL Sandbox article.

Queries

This section explores all available queries you can perform on your versioned applications.

To perform Application Versioning queries, use the preconfigured GraphQL sandbox documentation: 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. Selecting any of the available queries lets you add arguments and fields, and enter a payload in the Variables panel of the GraphQL sandbox. Arguments and a minimum of one field are required. Field selections depend on the data you want returned.

Enabling Application Versioning

Use the canChangeApplicationVersioningSetting query to determine if you can change the Application Versioning setting to a specific value. For example, if you want to disable Application Versioning, you'll send versioning: false in the payload. The returned canChange field determines whether you can change the value you sent. Doing so lets Unqork perform a check to determine how you want to change the setting. if you want to disable it, Unqork checks to see if you have version(s) created and return canChange: false.

Once enabled, you cannot disable Application Versioning.

This query contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID and a Boolean value of true. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request:

{
  "canChangeApplicationVersioningSettingInput": {
    // The ID of your application.
    "applicationId": "65709fbccc2b43b866d2eb45", 
    // To enable Application Versioning in your application.
    "versioning": true
  }
}

Generating Version Resolutions for an Application

Use the generateVersionResolutions query to generate version resolutions for a specified application.

This query contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
  "applicationInput": {
    // The ID of your application.
    "applicationId": "65709fbccc2b43b866d2eb45"
  }
}

Retrieving All Application Dependencies

Use the getAllAvailableDependencies query to retrieve all available dependencies in your environment.

This query provides the following fields to return in the response:

Retrieving an Application's Dependencies

Use the getAllApplicationVersionDependencies query to retrieve all dependencies for a versioned application.

This query contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID and version of the application. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
  "applicationVersionDependenciesInput": {
    // The ID of your application.
    "applicationId": "65709fbccc2b43b866d2eb45",
    // The application you want to query.
    "version": "1.0.0"
  }
}

Retrieving an Application Version

Use the getApplicationVersion query to retrieve a specific version of an application.

This query contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID and version of the application. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
  "getApplicationVersionInput": {
    // The ID of your application.
    "applicationId": "65709fbccc2b43b866d2eb45",
    // The version you want to query. If omitted, the active version is returned.
    "semanticVersion": "1.0.0"
  }
}

Retrieving Application Version History

Use the getApplicationVersionHistory query to retrieve version history for a specified application.

This query contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
  "getApplicationVersionHistoryInput": {
    // The ID of your application.
    "applicationId": "65709fbccc2b43b866d2eb45"
  }
}

Retrieving In-Progess Changes

Use the compareApplicationVersion query to retrieve information associated with the changes between the current and all recently created versions of a specified application.

This query contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
    // The ID of your application.
    "applicationId": "65709fbccc2b43b866d2eb45"
}

Retrieving Multiple Application Versions

Use the getApplicationVersionsBatch query to retrieve all application versions for a specified application.

This query contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
  "getApplicationVersionsBatchInput": {
    // The ID of your application.
    "applicationId": "65709fbccc2b43b866d2eb45"
  }
}

Retrieving the Next Application Version Number

Use the getNextVersion query to retrieve the next application version number for a specified application and release (or version) type.

This query contains the following arguments:

To make the call, you must provide the application ID and release type. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
  // The ID of your application.
  "applicationId": "65709fbccc2b43b866d2eb45",
  // Values include major, minor, or patch.
  "releaseType": "minor"
}

Mutations

This section explores all available mutations you can perform on your versioned applications in the GraphQL sandbox.

To perform Application Versioning mutations, use the preconfigured GraphQL sandbox documentation: 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. Selecting any of the available queries lets you add arguments and fields, and provide a payload in the Variables panel of the GraphQL sandbox. Arguments and a minimum of one field are required. Field selections depend on the data you want returned.

Adding an Application Dependency

Use the addApplicationDependencies mutation to add an application dependency.

To add an application dependency, that dependency must have Application Versioning enabled. You can only add one application version as a dependency to another application.

This mutation contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
  "applicationDependenciesInput": {
    // The ID of the application where you want to add the dependency.
    "applicationId": "65709fbccc2b43b866d2eb45",
    "dependencies": [
      {
        // The ID of the application dependency you want to add.
        "applicationId": "6582f327453b728e979a69ef",
        // The application dependency version you want to add.
        "version": "1.0.0"
      }
    ]
  }
}

Changing an Existing Application Dependency's Version Number

Use the updateApplicationDependencies mutation to change an existing application dependency's version number.

This mutation contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID and new application version number. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
  "applicationDependenciesInput": {
    // The ID of the application where the dependency exists.
    "applicationId": "65709fbccc2b43b866d2eb45",
    "dependencies": [
      {
        // The ID of the application dependency whose version number you want to change.
        "applicationId": "6582f327453b728e979a69ef",
        // The application dependency version you want to use.
        "version": "2.0.0"
      }
    ]
  }
}

Creating an Application Version

Use the createApplicationVersion mutation to create an application version.

This mutation contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID and the new application version number. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
  "applicationVersionInput": {
    // The ID of your application.
    "applicationId": "65709fbccc2b43b866d2eb45",
    // The new application version number.
    "version": "1.3.2",
    // Optional description of the new application version.
    "description": "Fixed the dashboard module to gracefully fail when the weather API is down."
  }
}

Removing an Application Dependency

Use the removeApplicationDependencies mutation to remove an application dependency from an application.

This mutation contains the following arguments:

It also lets you select the following fields to return in the response:

To make the call, you must provide the application ID and new application version number. Add and manipulate the following payload in the Variables panel of the GraphQL sandbox to make the request.

{
  "applicationDependenciesInput": {
    // The ID of the application where the dependency exists.
    "applicationId": "65709fbccc2b43b866d2eb45",
    "dependencies": [
      {
        // The ID of the application dependency you want to remove.
        "applicationId": "6582f327453b728e979a69ef",
        // The version number of the dependency you want to remove.
        "version": "2.0.0"
      }
    ]
  }
}

Promoting an Application Version

You can promote application versions, and their elements and dependencies, using Postman or another tool.

It's important to note that not all element types are currently integrated into application versioning. Promoting an application version will transfer both versioned and unversioned elements.

Versioned Elements

Versioned elements are all those contained in the versionResolutions data. These elements include modules, workflows, and transforms. Promoting these elements also promotes their archived version.

Unversioned Elements

Unversioned elements include Data Collections and Data Schemas. Because these elements are currently unversioned, they must be promoted as-is. Updating these elements can impact a specific application version.

Below is the required information to make the API call.

Below is an example of the necessary syntax to make the API call:

POST https://training.unqork.io/api/1.0/promote/applicationVersion 

{
    "clientName": "training",
    "clientLevel": "QA",
    "applicationId": "65709fbccc2b43b866d2eb45",
    "version": "1.0.0"
}

Resources

• Application Versioning

• How to: Use the GraphQL Sandbox