Confluence CLI Removing SOAP APIs

On this page

Summary

For over 10 years, the Confluence CLI primarily depended on Confluence's SOAP APIs. In the last couple of years, the Confluence CLI has been gradually replacing some of the SOAP APIs with newer REST APIs. This is mostly an internal implementation change with little or no external changes to the CLI. With the last few CLI 6.x releases, the pace to switch away from the remaining SOAP APIs has increased with the goal of complete elimination before CLI 7.0 is released in the summer of 2017. As this switch over proceeds, other improvements are also being made to standardize and modernize support. 

Unfortunately, Confluence REST APIs are still not complete replacements for the SOAP APIs. In those cases, we are switching over to the RPC APIs instead until the equivalent REST API becomes available from the Confluence team.

While we strive to maintain upward compatibility with functional capabilities and output (csv and other formats), there are some changes that may impact scripting that depends on other text. The following documents some of the things to watch if you have automation scripts using the CLI. 

With release 6.8, the conversion to REST APIs has been completed! Legacy SOAP support (see below) is still available for a short period of time. With this change, we have built the foundation for additional improvements and capabilities not possible before.

For those who are interested in more technical details: in some cases pseudo REST APIs (like RPC) are being used to cover cases where the official Confluence REST APIs still do not cover capabilities previous available in the SOAP APIs. It is expected Confluence REST APIs will add more coverage over time.

Potential Incompatibilities

While we strive to maintain upward compatibility of the interfaces by hiding many of the differences in the underlying Confluence APIs, some incompatibilities may surface. Here's a quick list of some things to be on the lookout for especially if you have automation scripts: 

  1. Text of error messages may be different. In some cases, the error message from the underlying API is surfaced directly and these have been changed by Atlassian. In other cases, we are issue our own messages and these may have changed. We also have made some improvements in this area.
  2. The class of error may have changed. If your script is sensitive to the exact return value (-1 versus -3 exit codes for example) then your script may need to be updated. Some errors formerly resulting from Confluence errors (error code -3) may now be intercepted and sent from the client (error code -1) likely with some additional information.
  3. login and logout actions will switch over to REST authentication instead of SOAP authentication
  4. Some parameter will be deprecated. Some are no longer available with the REST APIs and others have better replacement actions based on the newer support. 
    • search related parameters will be removed in favor of the more modern and powerful cql parameter
  5. removePage and removeBlog actions will require the --continue parameter to avoid failing on not found errors

Confluence Version Support

With the completion of this migration, CLI 7.0 will support Confluence 5.10 and higher. Legacy support will be completely removed. While it has been common practice in the past to successfully use newer CLI releases against older Confluence releases (not explicitly listed as being compatible), this will more like not be possible for many case. The older Confluence release may not support the newer REST APIs, so the action will fail.

Legacy Support

For a limited time only, you can use the --options legacy parameter to continue using the older support for most migrated support.

Watch This Page

Watch this page for updates as more information becomes available.