Problems with the Web API and the REST API Browser

Recently we have been made aware that the Web API extension for the projectdoc Toolbox for Confluence does constantly respond with HTTP 404 response codes. That has been surprising to us since we use our REST-based API frequently and also the projectdoc Toolbox itself heavily takes advantage of an internal REST API.

So we opened the REST API Browser which we have installed on our Confluence instance to easily interact with Confluence REST APIs, including our own. The REST Browser supports using the APIs by presenting documentation for the service and its parameters. This is of great help to explore APIs as far as the developers have provided some documentation.

Path Problem with the REST API Browser

We had a look at our APIs and indeed, as soon as we launched any REST call, the response is always 404.

We realized that the browser shows a wrong path to our REST services. Instead of projectdoc/1/document it shows projectdoc/1/projectdoc/1/document, having the first two path elements duplicated.

REST API with Path Problems on Confluence 6.14.x
REST API with Path Problems on Confluence 6.14.x

This is the case with REST API Browser version 3.2.2 and Confluence 6.14.1. Since the REST API Browser is not officially supporting the latest Confluence version (at the time of writing), we checked with the latest supported version 6.13.2. The result was the same. But the same REST API Browser on Confluence 5.10.9 did not show this issue. Also 6.12.1, 6.11.1, 6.10.2 and probably all previous version of Confluence 6.x do work and show the correct paths:

REST API without Path Problems on Confluence 5.10.x
REST API without Path Problems on Confluence 5.10.x

The problem is also shown for apps provided by Confluence, like the REST API of the AppLinks OAuth plugin.

REST API of Atlassian Plugin with Path Problems on Confluence 6.14.x
REST API of Atlassian Plugin with Path Problems on Confluence 6.14.x

The Cause

Digging a little deeper we realized that the problem went away for our app when we removed the package element from our configuration with the REST plugin module in the atlassian-plugin.xml.

This is the original configuration:

With package Element
  <rest name="projectdoc Web-API" 
        key="projectdocWebAPI" 
        path="/projectdoc"
        version="1">
    <description>Web access to projectdoc resources.</description>
    <package>de.smartics.projectdoc.extension.webapi</package>
  </rest>

Now with the package element removed, the paths are rendered correctly and calling the REST API does no longer return HTTP 404 responses.

Without package Element
  <rest name="projectdoc Web-API" 
        key="projectdocWebAPI" 
        path="/projectdoc" 
        version="1">
    <description>Web access to projectdoc resources.</description>
  </rest>

Checking with the AppLinks OAuth plugin our hypothesis seems to be supported.

Configuration of the AppLinks OAuth plugin
<rest key="applinksRestV2OAuth" 
      path="/applinks-oauth" 
      version="1.0" 
      description=
        "Provides REST endpoints for interacting with the AppLinks OAuth plugin">
  <package>com.atlassian.applinks.oauth.rest</package>
</rest>

Plugins that do not suffer from this all have no package element in their configuration.

The Workaround

Removing the package element from the REST configuration in the atlassian-plugin.xml makes the problem go away.

The downside of this workaround is that the browser would no longer render the documentation for the REST services.

Note that this is only experienced if you use the REST API Browser on versions of Confluence that actually produce this problem. On any Confluence version using an alternative REST client, for instance curl, does not produce this issue.

Ticket

We filed a bug report to Atlassian and they could reproduce the problem. Atlassian created a ticket CONFSERVER-57887 to track this issue.

You may would like to vote for it in case you are using the REST API Browser frequently with REST APIs that show this issue.

Resources

More information on how to use the Web API Extension for the projectdoc Toolbox with curl.

REST Login to Confluence with cURL
To access Confluence via its REST API with cURL you typically need to authenticate. Learn how to login with cURL and avoid some common security pitfalls.
Accessing projectdoc Space Properties with cURL
Learn how to access projectdoc space properties via REST API with cURL.
Accessing projectdoc Properties with cURL
Learn how to access projectdoc properties via REST API with cURL.