Purpose

Using the Confluence Server/Data Center REST API is useful to the Confluence administrator to automate some tasks.

The Universal Plugin Manager (UPM) has a set of API methods that may be helpful to automate some of the tasks associated to Marketplace Apps (aka Plugins or Addons) administration.

This document describes how to use the REST API to the following tasks:

• Install a Marketplace App.
• Uninstall a Marketplace App.
• Upgrade a Marketplace App.
• Downgrade a Marketplace App.

Solution

The following Sections will show an example of using the UPM REST API to perform a few tasks. You may also want to check the Atlassian Marketplace REST API.

These examples were coded using shell script, but you may port it to your preferred coding language.

Some of the shell commands use jq to parse the output data.

Installing a Marketplace App using the REST API

Here we are installing the Confluence Source Editor version 1.1.0, which is not the latest version.

1. Download the App .jar/.obr file from the Marketplace.

   APP_FILE_PATH=/tmp/confluence-source-editor-1.1.0.jar
   
   curl -k -L -o ${APP_FILE_PATH} https://marketplace.atlassian.com/download/apps/1210722/version/46
   ls -la ${APP_FILE_PATH}; file ${APP_FILE_PATH}

2. Get the UPM token, which is necessary on the next step.

   CONFLUENCE_SERVER_URL=http://localhost:21310
   CONFLUENCE_SERVER_CONTEXT_PATH=/c61310
   ADMIN_USRNAME=admin
   ADMIN_PWD=admin
   
   CONFLUENCE_BASE_URL=$CONFLUENCE_SERVER_URL$CONFLUENCE_SERVER_CONTEXT_PATH
   UPM_TOKEN=$(curl -I --user $ADMIN_USRNAME:$ADMIN_PWD -H 'Accept: application/vnd.atl.plugins.installed+json' $CONFLUENCE_BASE_URL'/rest/plugins/1.0/?os_authType=basic' 2>/dev/null | grep 'upm-token' | cut -d " " -f 2 | tr -d '\r')

3. Install the App.

   curl --user ${ADMIN_USRNAME}:${ADMIN_PWD} -H 'Accept: application/json' ${CONFLUENCE_BASE_URL}'/rest/plugins/1.0/?token='${UPM_TOKEN} -F plugin=@${APP_FILE_PATH}

4. Check if the App was properly installed.

   APP_NAME="Confluence Source Editor"
   
   curl --user $ADMIN_USRNAME:$ADMIN_PWD $CONFLUENCE_BASE_URL/rest/plugins/latest/ 2>/dev/null | jq -r '.plugins[] | select(.name | contains("'${APP_NAME}'"))'

Uninstalling a Marketplace App using the REST API

In this example we are uninstalling the same App that was installed in the previous Section.

1. Get the App key.

   CONFLUENCE_SERVER_URL=http://localhost:21310
   CONFLUENCE_SERVER_CONTEXT_PATH=/c61310
   ADMIN_USRNAME=admin
   ADMIN_PWD=admin
   
   APP_NAME="Confluence Source Editor"
   
   APP_KEY=$(curl --user $ADMIN_USRNAME:$ADMIN_PWD $CONFLUENCE_BASE_URL/rest/plugins/latest/ 2>/dev/null | jq -r '.plugins[] | select(.name | contains("'${APP_NAME}'")) | "\(.key)"')

2. Uninstall the App; an HTTP 204 response means it was uninstalled.

   curl -I --user ${ADMIN_USRNAME}:${ADMIN_PWD} -H 'Accept: application/json' -X DELETE ${CONFLUENCE_BASE_URL}'/rest/plugins/1.0/'${APP_KEY}'-key' 2>/dev/null

Upgrading a Marketplace App using the REST API

To upgrade an existing App you may download a more recent version from the Atlassian Marketplace and follow the same procedure described in the Installing a Marketplace App using the REST API Section.

Downgrading a Marketplace App using the REST API

Directly downgrading an App isn't possible, not even from the UPM UI.

In this case you need to follow these steps:

1. Uninstall the current installed version.
2. Download an old, target version of the App.
3. Install the target version of the App.

Do please note that when registering from the command line using cURL, keep in mind that cURL does not perform session maintenance across calls (unlike other clients, such as Apache HttpClient). In which case, this KB might come in handy:

Registering apps

See Also

Confluence Server REST API

UPM REST API

Atlassian Marketplace REST API

About the Universal Plugin Manager

Atlassian Marketplace

How to get a list of Confluence Apps and their licensing information

How to download Atlassian Marketplace apps through the command line