PluginResource

API for managing plugins. User must have ADMIN permission level in order to interact with the plugin manager API. The API exposes two main flows: installing or upgrading an officially supported Digital.ai plugin which is hosted over the official Nexus repository; and installing or upgrading an official or 3rd party plugin xldp via manual upload.

DELETE /{url:plugin-manager|api/v1/plugin-manager}//delete/{repositoryId}/{groupId}/{artifactId}{version:(/.*)?} Cancels pending installation of a plugin.
POST /{url:plugin-manager|api/v1/plugin-manager}/install Installs a plugin by uploading the plugin binary.
POST /{url:plugin-manager|api/v1/plugin-manager}/install-or-update Installs a plugin by uploading the plugin binary.
GET /{url:plugin-manager|api/v1/plugin-manager}/list Lists all plugins in the system (either in INSTALLED or READY_FOR_INSTALL status) with metadata for each plugin.
GET /{url:plugin-manager|api/v1/plugin-manager}/repositories Lists all configured Nexus repositories in order to later query for available official plugins.
POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/install-or-update/{groupId}/{artifactId}/{version} Downloads a plugin from repository and inserts it into the DB.
POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/install/{groupId}/{artifactId}/{version} Downloads a plugin from repository and inserts it into the DB.
POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/install/{groupId}/{artifactId}/{version}/{packaging} Downloads a plugin from repository and inserts it into the DB.
GET /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/list Lists all available plugins for the provided repositoryId.
GET /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/logo/{groupId}/{artifactId} Gets the plugin logo.
POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/update Updates cached list of available official plugins in the system for a given repository by downloading the metadata from the Nexus repository.
POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/update/{groupId}/{artifactId} Updates a plugin from repository and updates the DB.
POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/update/{groupId}/{artifactId}/{packaging} Updates a plugin from repository and updates the DB.
GET /{url:plugin-manager|api/v1/plugin-manager}/search/{query} The search is performed amongst all available plugins regardless of their installation status.
POST /{url:plugin-manager|api/v1/plugin-manager}/update Updates a plugin by uploading the plugin binary.

DELETE /{url:plugin-manager|api/v1/plugin-manager}//delete/{repositoryId}/{groupId}/{artifactId}{version:(/.*)?}

Cancels pending installation of a plugin. Plugin installation requires a restart of the system to be completed. The uninstall API call can be made on plugins in the READY_FOR_INSTALL status (which is the state of plugin after the install API call but before system restart). Note: once a plugin is in INSTALLED state it can not be deleted anymore. Returns an empty response with a status code of 200 (OK). In case if plugin with the provided data does not exist in the system returns a status code of 404 (NOT FOUND). In case of an uninstall API call for a plugin in INSTALLED status, returns a status code of 501 (NOT IMPLEMENTED).
Permissions
Available - only to admin
Parameters
Path repositoryId String the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
Path groupId String the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
Path artifactId String the name of artifact on the Nexus repository; for example, xld-docker-plugin
Path version String the version of the artifact which should be installed; for example, 10.1.0
Response body
Response - empty in case of successful cancellation or error message in case of failure
Content type:

POST /{url:plugin-manager|api/v1/plugin-manager}/install

Installs a plugin by uploading the plugin binary. It can either be an official plugin or a 3rd party plugin. Plugin installation requires a restart of the system to be completed. Endpoint has different behavior depending on the type of the plugin uploaded, official or local. The system will treat the uploaded file as an official plugin if the uploaded binary filename matches an entry in the official metadata. Match is searched for using artifactId only; version and extension are ignored. Returns an empty response with a status code of 200 (OK). In case of installation failure returns a status code of 400 (BAD REQUEST) with a response object containing the error message.
Permissions
Available - only to admin
Parameters
Request body multipart/form-data MultipartFormDataInput the plugin file data
Query pluginId String plugin filename; for example, xld-docker-plugin-9.2.0.xldp
Response body
Response - empty in case of successful installation or error message in case of failure
Content type:

POST /{url:plugin-manager|api/v1/plugin-manager}/install-or-update

Installs a plugin by uploading the plugin binary. It can either be an official plugin or a 3rd party plugin. Plugin installation requires a restart of the system to be completed. Endpoint has different behavior depending on the type of the plugin uploaded, official or local. Local: if a plugin already exists in the system, the one in the system will get overwritten on next system start. This will happen regardless of the plugin version (if it exists at all). I.e. local plugin upgrades and downgrades are allowed without any limitations. Official: if a plugin already exists in the system and the uploaded version is equal or higher than the plugin in the system then the system will overwrite the previous plugin on next system start. If the uploaded version is lower than the one in the system the uploaded binary is ignored. I.e. it's possible to use this endpoint for official plugin upgrades, but it's impossible to use it for downgrades. The system will treat the uploaded file as an official plugin if the uploaded binary filename matches an entry in the official metadata. Match is searched for using artifactId only; version and extension are ignored. If the plugin with the same name exists in the system, the system will replace the previous plugin, and it will do so regardless of the version (if it exists at all). Returns an empty response with a status code of 200 (OK). In case of installation failure returns a status code of 400 (BAD REQUEST) with a response object containing the error message.
Permissions
Available - only to admin
Parameters
Request body multipart/form-data MultipartFormDataInput the plugin file data
Query pluginId String plugin filename; for example, xld-docker-plugin-9.2.0.xldp
Response body
Response - empty in case of successful installation or error message in case of failure
Content type:

GET /{url:plugin-manager|api/v1/plugin-manager}/list

Lists all plugins in the system (either in INSTALLED or READY_FOR_INSTALL status) with metadata for each plugin. Returns a response with a status code of 200 (OK) and a list of plugins with all details.
Permissions
Available - only to admin
Response body
Response - a list of plugins in the system
Content type:

GET /{url:plugin-manager|api/v1/plugin-manager}/repositories

Lists all configured Nexus repositories in order to later query for available official plugins. Note that the response field `config.repository-id` is a mandatory parameter in some other API calls. The default repository id is xld-official. Returns a response with a status code of 200 (OK) and a list of repositories with all details.
Permissions
Available - only to admin
Response body
Response - a list of nexus repository objects from server configuration
Content type:

POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/install-or-update/{groupId}/{artifactId}/{version}

Downloads a plugin from repository and inserts it into the DB. Plugin is then in the READY_FOR_INSTALL status, and a system restart is needed for installation to be completed. The endpoint is for updating a plugin as well. The update scenario will get triggered if the plugin with passed repositoryId, groupId and artifactId is already in the system. Note: the endpoint can't be used for downgrading, only for upgrades. Returns a response with a status code of 200 (OK) and installed plugin information. If provided repositoryId is wrong then returns 404 (NOT FOUND). If there is an issue with plugin installation then returns 500 (INTERNAL SERVER ERROR).
Permissions
Available - only to admin
Parameters
Path repositoryId String the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
Path groupId String the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
Path artifactId String the name of artifact on the Nexus repository; for example, xld-docker-plugin
Path version String the version of the artifact which should be installed; for example, 10.1.0
Response body
Response - information on the installed plugin
Content type:

POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/install/{groupId}/{artifactId}/{version}

Downloads a plugin from repository and inserts it into the DB. Plugin is then in the READY_FOR_INSTALL status, and a system restart is needed for installation to be completed. Returns a response with a status code of 200 (OK) and installed plugin information. If provided repositoryId is wrong then returns 404 (NOT FOUND). If there is an issue with plugin installation then returns 500 (INTERNAL SERVER ERROR).
Permissions
Available - only to admin
Parameters
Path repositoryId String the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
Path groupId String the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
Path artifactId String the name of artifact on the Nexus repository; for example, xld-docker-plugin
Path version String the version of the artifact which should be installed; for example, 10.1.0
Response body
Response - information on the installed plugin
Content type:

POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/install/{groupId}/{artifactId}/{version}/{packaging}

Downloads a plugin from repository and inserts it into the DB. Plugin is then in the READY_FOR_INSTALL status, and a system restart is needed for installation to be completed. Returns a response with a status code of 200 (OK) and installed plugin information. If provided repositoryId is wrong then returns 404 (NOT FOUND). If there is an issue with plugin installation then returns 500 (INTERNAL SERVER ERROR).
Permissions
Available - only to admin
Parameters
Path repositoryId String the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
Path groupId String the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
Path artifactId String the name of artifact on the Nexus repository; for example, xld-docker-plugin
Path version String the version of the artifact which should be installed; for example, 10.1.0
Path packaging String the packaging of the artifact which should be installed; for example, jar, zip, xldp
Response body
Response - information on the installed plugin
Content type:

GET /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/list

Lists all available plugins for the provided repositoryId. Returns metadata and installation status per plugin. Server internally caches the received metadata so an update API call (`POST /plugin-manager/repositories/{repository-id}/update`) needs to be made periodically:. Returns a response with a status code of 200 (OK) and a list of all available official plugins for the provided repositoryId. If provided repositoryId is wrong then returns 404 (NOT FOUND).
Permissions
Available - only to admin
Parameters
Path repositoryId String the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
Response body
Response - a list of officially supported plugin objects for the given repository
Content type:

GET /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/logo/{groupId}/{artifactId}

Gets the plugin logo. Returns a response with a status code of 200 (OK) and the image file.
Permissions
Available - only to admin
Parameters
Path repositoryId String the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
Path groupId String the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
Path artifactId String the name of artifact on the Nexus repository; for example, xld-docker-plugin
Response body
Response - image file
Content type: image/*

POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/update

Updates cached list of available official plugins in the system for a given repository by downloading the metadata from the Nexus repository. Sometimes plugins are updated and released to Nexus so it is good to periodically do this API call in order to update the cached list of plugins in the system. The response contains date when repository metadata was downloaded from Nexus last time. Returns a response with a status code of 200 (OK) and a timestamp of the update.
Permissions
Available - only to admin
Parameters
Path repositoryId String identifier of the Nexus repository; for example, xld-official
Response body
Response - timestamp of the update
Content type:

POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/update/{groupId}/{artifactId}

Updates a plugin from repository and updates the DB. Plugin is then in the INSTALLED status, and a system restart is needed for installation to be completed. The update scenario will get triggered if the plugin with passed repositoryId, groupId and artifactId is already in the system. Note: the endpoint can't be used for downgrading, only for upgrades. Returns a response with a status code of 200 (OK) and updated plugin information. If provided repositoryId is wrong then returns 404 (NOT FOUND). If there is an issue with plugin installation then returns 500 (INTERNAL SERVER ERROR).
Permissions
Available - only to admin
Parameters
Path repositoryId String the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
Path groupId String the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
Path artifactId String the name of artifact on the Nexus repository; for example, xld-docker-plugin
Response body
Response - information on the updated plugin
Content type:

POST /{url:plugin-manager|api/v1/plugin-manager}/repositories/{repositoryId}/update/{groupId}/{artifactId}/{packaging}

Updates a plugin from repository and updates the DB. Plugin is then in the INSTALLED status, and a system restart is needed for installation to be completed. The update scenario will get triggered if the plugin with passed repositoryId, groupId and artifactId is already in the system. Note: the endpoint can't be used for downgrading, only for upgrades. Returns a response with a status code of 200 (OK) and updated plugin information. If provided repositoryId is wrong then returns 404 (NOT FOUND). If there is an issue with plugin installation then returns 500 (INTERNAL SERVER ERROR).
Permissions
Available - only to admin
Parameters
Path repositoryId String the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
Path groupId String the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
Path artifactId String the name of artifact on the Nexus repository; for example, xld-docker-plugin
Path packaging String the packaging of the artifact which should be installed; for example, jar, zip, xldp
Response body
Response - information on the updated plugin
Content type:

GET /{url:plugin-manager|api/v1/plugin-manager}/search/{query}

The search is performed amongst all available plugins regardless of their installation status. It's performed against the plugin id, which is a string in the following format: `repository-id:groupId:artifactId-version.extension` Search endpoint will try to find a plugin whose plugin id contains the provided `query` path parameter (no wildcards). Returns a response with a status code of 200 (OK) and a list of found plugins with all details.
Permissions
Available - only to admin
Parameters
Path query String the search query to be used for plugin lookup
Response body
Response - a list of found plugins
Content type:

POST /{url:plugin-manager|api/v1/plugin-manager}/update

Updates a plugin by uploading the plugin binary. It can either be an official plugin or a 3rd party plugin. Plugin update requires a restart of the system to be completed. Endpoint has different behavior depending on the type of the plugin uploaded, official or local. Local: if a plugin already exists in the system, the one in the system will get overwritten on next system start. This will happen regardless of the plugin version (if it exists at all). I.e. local plugin upgrades and downgrades are allowed without any limitations. Official: if a plugin already exists in the system and the uploaded version is equal or higher than the plugin in the system then the system will overwrite the previous plugin on next system start. If the uploaded version is lower than the one in the system the uploaded binary is ignored. I.e. it's possible to use this endpoint for official plugin upgrades, but it's impossible to use it for downgrades. The system will treat the uploaded file as an official plugin if the uploaded binary filename matches an entry in the official metadata. Match is searched for using artifactId only; version and extension are ignored. Returns an empty response with a status code of 200 (OK). In case of update failure returns a status code of 400 (BAD REQUEST) with a response object containing the error message.
Permissions
Available - only to admin
Parameters
Request body multipart/form-data MultipartFormDataInput the plugin file data
Query existingPluginName String plugin filename; for example, xld-docker-plugin-9.2.0.xldp
Query newPluginId String new version of the plugin
Response body
Response - empty in case of successful update or error message in case of failure
Content type: