Application Versioning: API Reference

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.

TIP  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.

TIP  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.

IMPORTANT  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 enable the Application Versioning setting in an application.

IMPORTANT  Once enabled, you cannot disable Application Versioning.

This query contains the following arguments:

Argument Description

canChangeApplicationVersioningSettingInput

The required argument lets you send a payload as part of the request in the Variables panel of the GraphQL sandbox.

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

Field Description Type

canChange

Whether Application Versioning is enabled for a specified application. Displays true if enabled; displays false if it is not.

Boolean

errors

If an error occurs in the call, it is returned.

String

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:

Copy
{
  "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:

Argument Description

applicationInput

The required argument lets you send a payload as part of the request in the Variables panel of the GraphQL sandbox.

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

Field Description Type

generateAt

The date and time when the version resolutions were generated.

Datetime

versionResolutions

Details on all dependency resolutions associated with modules, workflows, transforms, and styles.

TIP  Click this field to select more options to display in the response.

Multiple

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.

Copy
{
  "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:

Field Description Type

applicationId

The application's unique identifier.

String

applicationName

The application's name.

String

version

The application's current version number.

Semver

Retrieving an Application's Dependencies

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

This query contains the following arguments:

Argument Description

applicationVersionDependenciesInput

The required argument lets you send a payload as part of the request in the Variables panel of the GraphQL sandbox.

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

Field Description Type

applicationId

The application's unique identifier.

String

applicationName

The application's name.

String

applicationTitle

The application's title.

String

created

The date and time the application was created.

Datetime

modified

The date and time the application was last modified.

Datetime

version

The application's current version number.

Semver

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.

Copy
{
  "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:

Argument Description

getApplicationVersionInput

The required argument lets you send a payload as part of the request in the Variables panel of the GraphQL sandbox.

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

Field Description Type

active

Whether the specified application version is the active one. Displays true if active; displays false if it is not.

Boolean

applicationId

The application's unique identifier.

String

created

The date and time the application version was created.

Datetime

createdBy

The email address of the Creator that created the application version.

String

definition

The complete JSON definition of the application version.

TIP  Click this field to select more options to display in the response.

Multiple

description

The description explaining the changes that were made to the application when the version was created.

String

id

The unique identifier associated with this application version.

String

modified

The date and time the application version was last modified.

Datetime

modifiedBy

The email address of the Creator that modified the application version.

String

moduleImports

The unique identifiers for modules imported in the application version.

TIP  Click this field to select more options to display in the response.

Multiple

version

The application's version number.

Semver

versionResolutions

Details on all dependency resolutions associated with modules, workflows, transforms, and styles in the application version.

TIP  Click this field to select more options to display in the response.

Multiple

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.

Copy
{
  "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:

Argument Description

getApplicationVersionHistoryInput

The required argument lets you send a payload as part of the request in the Variables panel of the GraphQL sandbox.

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

Field Description Type

created

The date and time the application version was created.

Datetime

elements

The application's elements, including modules, workflows, transforms, and styles.

TIP  Click this field to select more options to display in the response.

Multiple

version

The application's version number.

String

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.

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

Retrieving In-Progess Changes

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

This query contains the following arguments:

Argument Description Type

applicationId

The application's unique identifier.

String

version

The release or version type. Values include major, minor, and patch.

TIP  To learn more about release types, view our Application Versioning article.

Semver

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

Field Description Type

changed

Details associated with changes made to app elements in the application. For example, if an application element was created, modified, or deleted.

TIP  Click this field to select more options to display in the response.

Multiple

unchanged

Details associated with application elements that were not changed in the application.

TIP  Click this field to select more options to display in the response.

Multiple

version

The application's version number.

Semver

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.

Copy
{
    // 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:

Argument Description

getApplicationVersionsBatchInput

The required argument lets you send a payload as part of the request in the Variables panel of the GraphQL sandbox.

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

Field Description Type

active

Whether the specified application version is the active one. Displays true if active; displays false if it is not.

Boolean

applicationId

The application's unique identifier.

String

created

The date and time the application version was created.

Datetime

createdBy

The email address of the Creator that created the application version.

String

definition

The complete JSON definition of the application version.

TIP  Click this field to select more options to display in the response.

Multiple

description

The description explaining the changes that were made to the application when the version was created.

String

id

The unique identifier associated with this application version.

String

modified

The date and time the application version was last modified.

Datetime

modifiedBy

The email address of the Creator that modified the application version.

String

moduleImports

The unique identifiers for modules imported in the application version.

TIP  Click this field to select more options to display in the response.

Multiple

version

The application's version number.

Semver

versionResolutions

Details on all dependency resolutions associated with modules, workflows, transforms, and styles in the application version.

TIP  Click this field to select more options to display in the response.

Multiple

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.

Copy
{
  "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:

Argument Description Type

applicationId

The application's unique identifier.

String

releaseType

The release or version type. Values include major, minor, and patch.

TIP  To learn more about release types, view our Application Versioning article.

String

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.

Copy
{
  // 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.

IMPORTANT  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.

IMPORTANT  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:

Argument Description

applicationVersionInput

The required argument lets you send a payload as part of the request in the Variables panel of the GraphQL sandbox.

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

Field Description Type

created

The date and time the application version was created.

Datetime

createdBy

The email address of the Creator that created the application version.

String

dataSchemas

JSON Schemas associated with the application.

JSON

dependencies

Information detailing the application dependencies.

TIP  Click this field to select more options to display in the response.

Multiple

description

The description of the application version.

String

folders

The folder structure storing the application's app elements.

JSON

id

The application's unique identifier.

String

modified

The date and time the application version was last modified.

Datetime

modifiedBy

The email address of the Creator that modified the application version.

String

name

The application's name.

String

origResource

The CORS Cross-Origin Resource Sharing (CORS) lets you control access to resources located outside a given domain. (Cross-Origin Resource Sharing) associated with the application.

String

previousVerisonId

The unique identifier of the application's previous version.

String

promotions

Information detailing the promotions of the application version.

JSON

settings

Information detailing the application's configured application settings.

TIP  Click this field to select more options to display in the response.

Multiple

title

The application's title.

String

type

The application type.

String

workspaceId

The unique identifier of the workspace where the application exists.

String

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.

Copy
{
  "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:

Argument Description

applicationInput

The required argument lets you send a payload as part of the request in the Variables panel of the GraphQL sandbox.

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

Field Description Type

created

The date and time the application version was created.

Datetime

createdBy

The email address of the Creator that created the application version.

String

dataSchemas

JSON Schemas associated with the application.

JSON

dependencies

Information detailing the application dependencies.

TIP  Click this field to select more options to display in the response.

Multiple

description

The description of the application version.

String

folders

The folder structure storing the application's app elements.

JSON

id

The application's unique identifier.

String

modified

The date and time the application version was last modified.

Datetime

modifiedBy

The email address of the Creator that modified the application version.

String

name

The application's name.

String

origResource

The CORS Cross-Origin Resource Sharing (CORS) lets you control access to resources located outside a given domain. (Cross-Origin Resource Sharing) associated with the application.

String

previousVerisonId

The previous unique identifier of the application's previous version.

String

promotions

Information detailing the promotions of the application version.

JSON

settings

Information detailing the application's configured application settings.

TIP  Click this field to select more options to display in the response.

Multiple

title

The application's title.

String

type

The application type.

String

workspaceId

The unique identifier of the workspace where the application exists.

String

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.

Copy
{
  "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:

Argument Description

applicationVersionInput

The required argument lets you send a payload as part of the request in the Variables panel of the GraphQL sandbox.

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

Field Description Type

active

Whether the specified application version is the active one.

IMPORTANT  The new application version automatically becomes the active version.

Boolean

applicationId

The application's unique identifier.

String

created

The date and time the application version was created.

Datetime

createdBy

The email address of the Creator that created the application version.

String

definition

The complete JSON definition of the application version.

TIP  Click this field to select more options to display in the response.

Multiple

description

The description explaining the changes that were made to the application when the version was created.

String

id

The unique identifier associated with this application version.

String

modified

The date and time the application version was last modified.

Datetime

modifiedBy

The email address of the Creator that modified the application version.

String

moduleImports

The unique identifiers for modules imported in the application version.

TIP  Click this field to select more options to display in the response.

Multiple

version

The application's version number.

Semver

versionResolutions

Details on all dependency resolutions associated with modules, workflows, transforms, and styles.

TIP  Click this field to select more options to display in the response.

Multiple

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.

Copy
{
  "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:

Argument Description

applicationInput

The required argument lets you send a payload as part of the request in the Variables panel of the GraphQL sandbox.

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

Field Description Type

created

The date and time the application version was created.

Datetime

createdBy

The email address of the Creator that created the application version.

String

dataSchemas

JSON Schemas associated with the application.

JSON

dependencies

Information detailing the application dependencies.

TIP  Click this field to select more options to display in the response.

Multiple

description

The description of the application version.

String

folders

The folder structure storing the application's app elements.

JSON

id

The application's unique identifier.

String

modified

The date and time the application version was last modified.

Datetime

modifiedBy

The email address of the Creator that modified the application version.

String

name

The application's name.

String

origResource

The CORS (Cross-Origin Resource Sharing) associated with the application.

String

previousVerisonId

The previous unique identifier of the application's previous version.

String

promotions

Information detailing the promotions of the application version.

JSON

settings

Information detailing the application's configured application settings.

TIP  Click this field to select more options to display in the response.

Multiple

title

The application's title.

String

type

The application type.

String

workspaceId

The unique identifier of the workspace where the application exists.

String

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.

Copy
{
  "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"
      }
    ]
  }
}

Resources