New Download attachment REST API endpoint

What is changing?

We have created a new OAuth 2.0 (3LO) scope readonly:content.attachment:confluence that gives 3LO apps permission to download attachments. Furthermore, we have created a new endpoint that can be used to download a content attachment.

Calling the endpoint will return a 302 redirect to a URL that can be accessed to directly download the file attachment.

See the details of the new endpoint in the documentation when it is available.

Why is it changing?

3LO apps are not intended to access the Confluence UI link for downloading an attachment ( /wiki/download/attachments/<contentId>/<filename>?api=v2 ). 3LO apps should always use the documented REST API, accessed through the api.atlassian.com host.

Nonetheless, they had previously been able to access this link to download an attachment. We recently released changes that removed 3LO apps’ ability to use this link, which broke any app that relied it. Developers communicated to us the impact of our changes in a number of Community posts:

In order to restore this functionality and address the impact, we have created a new documented endpoint and respective OAuth 2.0 (3LO) scope.

What do I need to do?

Developers who rely on the ability to download attachments should use the new Download attachment endpoint.

By when do I need to do it?

The endpoint will be available on Thursday, 29 July.

6 Likes

Would be nice if this was also usable using AP.request().

2 Likes

Hi @candid, Connect apps can also use this endpoint so long as they have declared the READ scope.

1 Like

@LucasPan Connect apps can access the endpoint, but because AP.request() returns the data from XMLHttpRequest.responseText, any bytes above 0x7f are damaged, making it impossible to use it to fetch binary data.

See How to get confluence page attachments as BLOB - #4 by candid.

4 Likes

Hi @candid, you’re quite right; there seems to be an issue right now with AP.request that will prevent apps from properly using this endpoint to get an attachment in binary form (such as images). I’ve created a new ticket to track this: https://jira.atlassian.com/browse/CONFCLOUD-72542.

In the meantime, as a workaround, one can get the non-REST download link by calling the /wiki/rest/api/content/{attachmentId} API (or /wiki/rest/api/content/{contentId}?expand=children.attachment), and looking for the _links.download property for the attachment in the response. This URL is usable by Connect apps in the browser - e.g. for an image, the URL can be directly embedded as <img src=URL />.

1 Like

as a workaround, one can get the non-REST download link by calling the /wiki/rest/api/content/{attachmentId} API (or /wiki/rest/api/content/{contentId}?expand=children.attachment ), and looking for the _links.download property for the attachment in the response

That works for the browser, but that URI results in a 403 for OAuth authenticated requests (the whole reason this new REST API endpoint was added). Will the _links.download and _links.base be updated to be correct for OAuth APIs when requested via OAuth APIs?

1 Like

Hey @LucasPan, I’m confused about that workaround. As far as I can tell, the _links.download property simply contains the /download/attachments/<contentId>/<filename>?api=v2 URL, so it doesn’t really solve anything?

Hi @candid, I’ve replied to your question on the ticket.

Hi @RandySwift, OAuth 2.0 (3LO) apps should use the REST API directly. This bug only affects Connect apps using AP.request. We do not currently have plans to change the _links.download and _links.base values, since not all the provided links are related to the REST API.