Application and Build Management APIs

This section describes all the APIs to manage the app builds for the TIBCO Flogo Capability.

Note: To use a namespace other than the default data plane namespace for APIs using the Namespace parameter, see Deploying App Outside Data Plane Namespace.

You can find the following APIs in the 'Apps and Builds' section of the TIBCO Flogo® Capability APIs page. For instructions on how to access the APIs, see Accessing the API Documentation with Swagger UI.

API for Listing Flogo Applications

Use the GET /v1/dp/apps API to retrieve a list of all Flogo applications from a data plane.

This API supports optional query parameters to filter the applications based on specified keys and values.

Optional Query Parameters:

Parameter Name	Type	Required	Description
filterKey	Query	No	A comma-separated list of columns to filter the result. For example: name, namespace, state, version, tag.
filterValue	Query	No	A comma-separated list of values to filter the result. For example: my-app, my-ns, Running, 1.0.0, tag1.

API for Deleting an Application

Use the DELETE /v1/dp/apps/{appId} API to delete an application from a data plane.

Required and Optional API Parameters:

Parameter Name	Type	Required	Description
appId	Path	Yes	The application ID of the app to delete.
namespace	Query	No	The namespace where the application is deployed. This parameter is required only if the application is running outside of the default data plane namespace.

API for Viewing Application Details

Use the GET /v1/dp/apps/{appId}/details API to view the application details for a specified app Id.

Required and Optional API Parameters:

Parameter Name	Type	Required	Description
appId	Path	Yes	The application ID of the app to view details for.
namespace	Query	No	The namespace where the application is deployed. This parameter is required only if the application is running outside of the default data plane namespace.

API for Listing Application Instances

Use the GET /v1/dp/apps/{appId}/instances API to retrieve a list of application instances for a specified app Id.

Required and Optional API Parameters:

Parameter Name	Type	Required	Description
appId	Path	Yes	The application ID of the app instance.
namespace	Query	No	The namespace where the application is deployed. This parameter is required only if the application is running outside of the default data plane namespace.

API for Viewing Application Endpoints

Use the GET /v1/dp/apps/{appId}/endpoints API to return a list of both the public and private application endpoints for a specified app Id. This API returns details about a private or public endpoint and the Ingress configuration for the public endpoint.

Required and Optional API Parameters:

Parameter Name	Type	Required	Description
appId	Path	Yes	The application ID of the app to view its app endpoints.
namespace	Query	No	The namespace where the application is deployed. This parameter is required only if the application is running outside of the default data plane namespace.

API for Scaling an Application

Use the PUT /v1/dp/apps/{appId}/scale/{count} API to scale the number of instances for an existing application to the count you specify.

Caution: Avoid using the scale operation when the auto scaling option is configured.

Required and Optional API Parameters:

Parameter Name	Type	Required	Description
appId	Path	Yes	The application ID of the app to scale.
count	Path	Yes	The number of count for scaling
namespace	Query	No	The namespace where the application is deployed. This parameter is required only if the application is running outside of the default data plane namespace.

API for Updating (Refreshing) Application Properties without Application Restart

Use the PUT /v1/dp/apps/{appId}/config/refresh API to update the application properties without restarting the app instance, if the app property reconfigure is enabled.

Before you begin

You must set the engine variable FLOGO_APP_PROP_RECONFIGURE to true to update the application configuration for that particular app.

Required and Optional API Parameters:

Parameter Name	Type	Required	Description
appId	Path	Yes	The application ID of the app to update the app properties.
namespace	Query	No	The namespace where the application is deployed. This parameter is required only if the application is running outside of the default data plane namespace.

Note: The list of config in key value pairs to update the app properties must be identical to its counterpart (app property) in the Application Properties dialog in Flogo. If the parameter names do not match exactly, a warning message is displayed, and the app uses the default value that you configured for the property in Flogo.

API for Listing Flogo Application Builds

Use the GET /v1/dp/builds API to retrieve a list of the TIBCO Flogo application builds on a data plane.

This API supports optional query parameters to filter the builds based on specified keys and values. Additionally, it supports parameters to sort and order the output.

Optional Query Parameters:

Parameter Name	Type	Required	Description
filterKey	Query	No	A comma-separated list of columns to filter the result. For example: buildId, name.
filterValue	Query	No	A comma-separated list of values to filter the result. For example: 0bb4dad, my-app-build.
sortBy	Query	No	The name of the column to sort the result. For example: createdDate
orderBy	Query	No	Specifies the order of the result. Available values: asc (ascending) and desc (descending).

API for Building an Application Executable Using app.json or app.flogo File

Use the POST /v1/dp/builds API to build a TIBCO Flogo application executable.

This API requires app.json or app.flogo binary file and request payload (optional) to build Flogo application. This API also supports optional query parameters for the baseVersion, OS, and arch.

Optional Query Parameters:

Parameter Name	Type	Required	Description
baseversion	Query	No	The TIBCO Flogo base version.
OS	Query	No	Compatible operating system for app binary. Available values: linux, darwin, windows
arch	Query	No	Compatible system architecture for app binary. Available values: amd64, 386

Parameter Name

Type

Required

Description

baseversion

Query

The TIBCO Flogo base version.

Query

Compatible operating system for app binary.

Available values: linux, darwin, windows

arch

Query

Compatible system architecture for app binary.

Available values: amd64, 386

Request body

app.json (type: string, format: binary, required)

The app.json or app.flogo file used to build the application.

request (object, optional)

An optional JSON part of the multipart request body that can contain buildName, dependencies, and tags. The dependencies field allows you to specify the versions of Connectors or Custom Extensions to use in your build.

'request' Object Fields

Note: All fields in the following table are optional. You can add multiple entries in the dependencies array to include more than one Connector or Custom extension in the build.

Field	Type	Description
`buildName`	string	A custom name for the build.
`dependencies`	string	A list of Connectors or Custom Extensions to include.
`dependencies[].id`	string	The unique identifier of the connector/extension.
`dependencies[].name`	string	The display name of the connector/extension.
`dependencies[].version`	string	The version of the connector/extension to use.
`tags`	array of strings	Tags to associate with the build.

Usage

In the Request body section, click Choose File, browse to the app.json or app.flogo file, and click Open.
Optionally, provide a request object with build-specific parameters, such as Connector/Custom Extension versions or tags.
Run the request to build the application executable.

API for Importing an App Build

Use the PUT /v1/dp/builds API to import an app build into a data plane.

To import an app build, you need the app build .zip file.

In the Request body section, click Choose File, browse to the .zip file, and click Open.

API for Downloading an Application Executable

Use the GET /v1/dp/builds/{buildId} API to download an application executable for an existing build Id.

Required Parameters:

Parameter Name	Type	Required	Description
buildId	Path	Yes	The application build ID to download the application executable.

API for Deleting Application Builds

Use the DELETE /v1/dp/builds/{buildId} API to delete an app build.

Note:

Ensure the application build being deleted is not used by any other application.
If the application build is tagged as DoNotDelete, the delete operation fails with an error. Remove the DoNotDelete tag from the build before attempting to delete it.

Required Parameters:

Parameter Name	Type	Required	Description
buildId	Path	Yes	The application build ID to delete the build.

API for Listing Flogo Applications from a Build ID

Use the GET /v1/dp/builds/{buildId}/apps API to retrieve a list of all TIBCO Flogo applications deployed using the specified build ID on a data plane.

This API requires a path parameter for the build ID and supports an optional query parameter to filter the applications by namespace.

Required and Optional API Parameters:

Parameter Name	Type	Required	Description
buildId	Path	Yes	The build ID for which you want to retrieve the list of applications.
namespace	Query	No	The namespace to filter the list of Flogo applications.

API for Exporting the app.json or app.flogo File

Use the GET /v1/dp/builds/{buildId}/export API to export the app.json or app.flogo file for an existing build Id.

Required Path Parameter:

Parameter Name	Type	Required	Description
buildId	Path	Yes	The application build ID to export the app.json or app.flogo file.

API for Exporting an Application Build

Use the GET /v1/dp/builds/{buildId}/exportBuild API to export an application build executable of an existing build Id.

Required API Parameter:

Parameter Name	Type	Required	Description
buildId	Path	Yes	The application build ID to download the application build executable.

API for Retrieving Detailed Application Build Information

Use the GET /v1/dp/builds/{buildId}/info API to retrieve detailed information about a specific build, including the build OS, architecture, base version, build time, and more, for the specified build ID.

Required API Parameter:

Parameter Name	Type	Required	Description
buildId	Path	Yes	The build ID for which you want to retrieve detailed information.

API for Retrieving Build Status

Use the GET /v1/dp/builds/{buildId}/status API to get the build status for the provided build ID. The status can be Building, Success, or Failure.

Required API Parameter:

Parameter Name	Type	Required	Description
buildId	Path	Yes	The build ID for which you want to retrieve the build status.

API for Bulk Tagging, Untagging, and Cleanup of Application Builds

Use the DELETE /v1/dp/builds API to perform bulk lifecycle management of application builds based on build age.

This API supports tagging builds for review, untagging mistakenly tagged builds, and cleaning up (deleting) old unused builds.

Query Parameters:

Parameter Name	Type	Required	Description
ageInDays	Query	Yes	The minimum age of builds (in days) to qualify for the action. Must be a non-negative integer (>= 0). Use `0` to target all unused builds, regardless of age. Negative values are rejected with a `400 Bad Request` error.
mode	Query	Yes	The action to perform on matching builds. Available values: `tag`, `untag`, `cleanup`.

Mode Descriptions:

Mode	Description
tag	Tags all unused builds older than the specified age (in days) with an identifying tag (for example, `olderthan10days`). Use this as a validation step before cleanup. Tagged builds can be reviewed in the platform UI before proceeding with deletion.
untag	Removes previously applied age-based tags from matching builds without deleting them. Use this to reverse a mistaken tag operation.
cleanup	Permanently deletes all unused builds older than the specified age (in days). Builds tagged with `DoNotDelete` are protected and are not removed during cleanup.

Suggested Workflow:

Tag - Run with mode=tag to tag builds matching your age criteria, and verify in the platform UI that the correct builds are selected.
Review - Inspect the tagged builds. If the selection is incorrect, run mode=untag to reverse the tags.
Cleanup - Run with mode=cleanup to permanently delete the matching builds.

Sample Requests:

Tag builds older than 30 days:

curl -X DELETE '<provisioner-host>/public/v1/dp/builds?ageInDays=30&mode=tag' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'

Untag previously tagged builds:

curl -X DELETE '<provisioner-host>/public/v1/dp/builds?ageInDays=30&mode=untag' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'

Clean up (delete) builds older than 30 days:

curl -X DELETE '<provisioner-host>/public/v1/dp/builds?ageInDays=30&mode=cleanup' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'

Sample Response (Tag Mode):

[
  {
    "buildId": "6168fc67b7b64e2e96cbf4036b27c982",
    "status": "SUCCESS",
    "message": "Tagged build 6168fc67b7b64e2e96cbf4036b27c982 with tag olderthan30days"
  }
]

Error Responses:

Negative ageInDays value:

{
  "errCode": "FLOGO-PLT-1001",
  "errMsg": "Bad Request",
  "errDetail": "ageInDays must be a non-negative integer, got: -1"
}

Attempting to clean up a build with the DoNotDelete tag:

The API returns an error for builds protected with the DoNotDelete tag and skips their deletion.

Caution: The cleanup mode permanently deletes builds. This action cannot be undone. Always use tag mode first to verify the set of builds before running cleanup.

Note: Builds that are in use are excluded from tag, untag, and cleanup operations. Builds protected with the DoNotDelete tag are excluded from cleanup operations. To protect a build from accidental deletion, add the DoNotDelete tag to the build in the platform UI before running cleanup.

Did you find this helpful?

Yes No