Package com.xebialabs.plugin.manager.rest.api

Interface PluginResource

@Path("/{url:plugin-manager|api/v1/plugin-manager}") @Produces("application/json") public interface 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.

  • Method Summary

    Modifier and Type
    Method
    Description
    jakarta.ws.rs.core.Response
    getLogo(String repositoryId, String groupId, String artifactId)
    Gets the plugin logo.
    jakarta.ws.rs.core.Response
    install(jakarta.servlet.http.HttpServletRequest request, String pluginId)
    Installs a plugin by uploading the plugin binary.
    jakarta.ws.rs.core.Response
    installFromRepository(String repositoryId, String groupId, String artifactId, String version)
    Deprecated.
    jakarta.ws.rs.core.Response
    installFromRepository(String repositoryId, String groupId, String artifactId, String version, String packaging)
    Downloads a plugin from repository and inserts it into the DB.
    jakarta.ws.rs.core.Response
    installOrUpdate(jakarta.servlet.http.HttpServletRequest request, String pluginId)
    Deprecated.
    jakarta.ws.rs.core.Response
    installOrUpdateFromRepository(String repositoryId, String groupId, String artifactId, String version)
    Deprecated.
    jakarta.ws.rs.core.Response
    list()
    Lists all plugins in the system (either in INSTALLED or READY_FOR_INSTALL status) with metadata for each plugin.
    jakarta.ws.rs.core.Response
    listRepositories()
    Lists all configured Nexus repositories in order to later query for available official plugins.
    jakarta.ws.rs.core.Response
    listRepository(String repositoryId)
    Lists all available plugins for the provided repositoryId.
    jakarta.ws.rs.core.Response
    search(String query)
    The search is performed amongst all available plugins regardless of their installation status.
    jakarta.ws.rs.core.Response
    uninstall(String repositoryId, String groupId, String artifactId, String version)
    Cancels pending installation of a plugin.
    jakarta.ws.rs.core.Response
    update(jakarta.servlet.http.HttpServletRequest request, String existingPluginName, String newPluginId)
    Updates a plugin by uploading the plugin binary.
    jakarta.ws.rs.core.Response
    updateFromRepository(String repositoryId, String groupId, String artifactId)
    Deprecated.
    jakarta.ws.rs.core.Response
    updateFromRepository(String repositoryId, String groupId, String artifactId, String packaging)
    Updates a plugin from repository and updates the DB.
    jakarta.ws.rs.core.Response
    updateRepository(String repositoryId)
    Updates cached list of available official plugins in the system for a given repository by downloading the metadata from the Nexus repository.

  • Method Details

    • list

      @GET @Path("list") @Produces("application/json") jakarta.ws.rs.core.Response list()
      Lists all plugins in the system (either in INSTALLED or READY_FOR_INSTALL status) with metadata for each plugin.
      Returns:
      a list of plugins in the system
      RestDetails:
      Returns a response with a status code of 200 (OK) and a list of plugins with all details.
      Permission:
      Available only to admin
      ApiDetails:
      Returns a response with a status code of 200 (OK) and a list of plugins with all details.

    • listRepositories

      @GET @Path("repositories") @Produces("application/json") jakarta.ws.rs.core.Response listRepositories()
      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 list of nexus repository objects from server configuration
      RestDetails:
      Returns a response with a status code of 200 (OK) and a list of repositories with all details.
      Permission:
      Available only to admin
      ApiDetails:
      Returns a response with a status code of 200 (OK) and a list of repositories with all details.

    • listRepository

      @GET @Path("repositories/{repositoryId}/list") @Produces("application/json") jakarta.ws.rs.core.Response listRepository(@PathParam("repositoryId") String repositoryId)
      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:.
      Parameters:
      repositoryId - the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
      Returns:
      a list of officially supported plugin objects for the given repository
      RestDetails:
      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).
      Permission:
      Available only to admin
      ApiDetails:
      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).

    • installOrUpdateFromRepository

      @POST @Path("repositories/{repositoryId}/install-or-update/{groupId}/{artifactId}/{version}") @Produces("application/json") @Deprecated jakarta.ws.rs.core.Response installOrUpdateFromRepository(@PathParam("repositoryId") String repositoryId, @PathParam("groupId") String groupId, @PathParam("artifactId") String artifactId, @PathParam("version") String version)
      Deprecated.
      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.
      Parameters:
      repositoryId - the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
      groupId - the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
      artifactId - the name of artifact on the Nexus repository; for example, xld-docker-plugin
      version - the version of the artifact which should be installed; for example, 10.1.0
      Returns:
      information on the installed plugin
      RestDetails:
      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).
      Permission:
      Available only to admin
      ApiDetails:
      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).

    • installFromRepository

      @POST @Path("repositories/{repositoryId}/install/{groupId}/{artifactId}/{version}") @Produces("application/json") @Deprecated(since="23.3.0") jakarta.ws.rs.core.Response installFromRepository(@PathParam("repositoryId") String repositoryId, @PathParam("groupId") String groupId, @PathParam("artifactId") String artifactId, @PathParam("version") String version)
      Deprecated.
      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.
      Parameters:
      repositoryId - the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
      groupId - the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
      artifactId - the name of artifact on the Nexus repository; for example, xld-docker-plugin
      version - the version of the artifact which should be installed; for example, 10.1.0
      Returns:
      information on the installed plugin
      RestDetails:
      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).
      Permission:
      Available only to admin
      ApiDetails:
      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).

    • installFromRepository

      @POST @Path("repositories/{repositoryId}/install/{groupId}/{artifactId}/{version}/{packaging}") @Produces("application/json") jakarta.ws.rs.core.Response installFromRepository(@PathParam("repositoryId") String repositoryId, @PathParam("groupId") String groupId, @PathParam("artifactId") String artifactId, @PathParam("version") String version, @PathParam("packaging") String 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.
      Parameters:
      repositoryId - the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
      groupId - the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
      artifactId - the name of artifact on the Nexus repository; for example, xld-docker-plugin
      version - the version of the artifact which should be installed; for example, 10.1.0
      packaging - the packaging of the artifact which should be installed; for example, jar, zip, xldp
      Returns:
      information on the installed plugin
      RestDetails:
      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).
      Permission:
      Available only to admin
      ApiDetails:
      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).

    • updateFromRepository

      @POST @Path("repositories/{repositoryId}/update/{groupId}/{artifactId}") @Produces("application/json") @Deprecated(since="23.3.0") jakarta.ws.rs.core.Response updateFromRepository(@PathParam("repositoryId") String repositoryId, @PathParam("groupId") String groupId, @PathParam("artifactId") String artifactId)
      Deprecated.
      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.
      Parameters:
      repositoryId - the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
      groupId - the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
      artifactId - the name of artifact on the Nexus repository; for example, xld-docker-plugin
      Returns:
      information on the updated plugin
      RestDetails:
      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).
      Permission:
      Available only to admin
      ApiDetails:
      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 update then returns 500 (INTERNAL SERVER ERROR).

    • updateFromRepository

      @POST @Path("repositories/{repositoryId}/update/{groupId}/{artifactId}/{packaging}") @Produces("application/json") jakarta.ws.rs.core.Response updateFromRepository(@PathParam("repositoryId") String repositoryId, @PathParam("groupId") String groupId, @PathParam("artifactId") String artifactId, @PathParam("packaging") String 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.
      Parameters:
      repositoryId - the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
      groupId - the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
      artifactId - the name of artifact on the Nexus repository; for example, xld-docker-plugin
      packaging - the packaging of the artifact which should be installed; for example, jar, zip, xldp
      Returns:
      information on the updated plugin
      RestDetails:
      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).
      Permission:
      Available only to admin
      ApiDetails:
      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 update then returns 500 (INTERNAL SERVER ERROR).

    • installOrUpdate

      @POST @Path("install-or-update") @Consumes("multipart/form-data") @Deprecated jakarta.ws.rs.core.Response installOrUpdate(@Context jakarta.servlet.http.HttpServletRequest request, @QueryParam("pluginId") String pluginId)
      Deprecated.
      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).
      Parameters:
      request - the plugin file data
      pluginId - plugin filename; for example, xld-docker-plugin-9.2.0.xldp
      Returns:
      empty in case of successful installation or error message in case of failure
      RestDetails:
      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.
      Permission:
      Available only to admin
      ApiDetails:
      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.

    • install

      @POST @Path("install") @Consumes("multipart/form-data") jakarta.ws.rs.core.Response install(@Context jakarta.servlet.http.HttpServletRequest request, @QueryParam("pluginId") String pluginId)
      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.
      Parameters:
      request - the plugin file data
      pluginId - plugin filename; for example, xld-docker-plugin-9.2.0.xldp
      Returns:
      empty in case of successful installation or error message in case of failure
      RestDetails:
      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.
      Permission:
      Available only to admin
      ApiDetails:
      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.

    • update

      @POST @Path("update") @Consumes("multipart/form-data") jakarta.ws.rs.core.Response update(@Context jakarta.servlet.http.HttpServletRequest request, @QueryParam("existingPluginName") String existingPluginName, @QueryParam("newPluginId") String newPluginId)
      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.
      Parameters:
      request - the plugin file data
      existingPluginName - plugin filename; for example, xld-docker-plugin-9.2.0.xldp
      newPluginId - new version of the plugin
      Returns:
      empty in case of successful update or error message in case of failure
      RestDetails:
      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.
      Permission:
      Available only to admin
      ApiDetails:
      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.

    • uninstall

      @DELETE @Path("/delete/{repositoryId}/{groupId}/{artifactId}{version:(/.*)?}") jakarta.ws.rs.core.Response uninstall(@PathParam("repositoryId") String repositoryId, @PathParam("groupId") String groupId, @PathParam("artifactId") String artifactId, @PathParam("version") String 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.
      Parameters:
      repositoryId - the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
      groupId - the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
      artifactId - the name of artifact on the Nexus repository; for example, xld-docker-plugin
      version - the version of the artifact which should be installed; for example, 10.1.0
      Returns:
      empty in case of successful cancellation or error message in case of failure
      RestDetails:
      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).
      Permission:
      Available only to admin
      ApiDetails:
      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).

    • search

      @GET @Path("search/{query}") @Produces("application/json") jakarta.ws.rs.core.Response search(@PathParam("query") String 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).
      Parameters:
      query - the search query to be used for plugin lookup
      Returns:
      a list of found plugins
      RestDetails:
      Returns a response with a status code of 200 (OK) and a list of found plugins with all details.
      Permission:
      Available only to admin
      ApiDetails:
      Returns a response with a status code of 200 (OK) and a list of found plugins with all details.

    • updateRepository

      @POST @Path("repositories/{repositoryId}/update") jakarta.ws.rs.core.Response updateRepository(@PathParam("repositoryId") String repositoryId)
      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.
      Parameters:
      repositoryId - identifier of the Nexus repository; for example, xld-official
      Returns:
      timestamp of the update
      RestDetails:
      Returns a response with a status code of 200 (OK) and a timestamp of the update.
      Permission:
      Available only to admin
      ApiDetails:
      Returns a response with a status code of 200 (OK) and a timestamp of the update.

    • getLogo

      @GET @Path("repositories/{repositoryId}/logo/{groupId}/{artifactId}") @Produces("image/*") jakarta.ws.rs.core.Response getLogo(@PathParam("repositoryId") String repositoryId, @PathParam("groupId") String groupId, @PathParam("artifactId") String artifactId)
      Gets the plugin logo.
      Parameters:
      repositoryId - the Nexus repository ID on which plugin is accessible (in case of 3rd party plugins it should be $$__local__$$); for example, xld-official
      groupId - the coordinates of plugin on the Nexus repository (in case of 3rd party plugins it should be $$__local__$$); for example, com.xebialabs.deployit.plugins
      artifactId - the name of artifact on the Nexus repository; for example, xld-docker-plugin
      Returns:
      image file
      RestDetails:
      Returns a response with a status code of 200 (OK) and the image file.
      Permission:
      Available only to admin
      ApiDetails:
      Returns a response with a status code of 200 (OK) and the image file.