Confluence REST API v2: Update to v1 Deprecation Timeline

Confluence Development Confluence Cloud
, , ,
1

Hi All -

We wanted to use this post to provide more context on the announcement changelog here CHANGE-1315 and an update on the timeline of ongoing deprecation of endpoints noted in CHANGE-864 and CHANGE-1116 and detailed in RFC-19: Deprecation of Confluence Cloud REST API v1 Endpoints. To ensure app developers have additional time to complete their migrations, we have decided to postpone the removal of service for all endpoints until at least June 2024 and will announce a new date soon.

We want to reassure the community that we will not remove access to any endpoint until there is at least 6 months of feature parity in the v2 API. We also wanted to use this post as an opportunity to thank the community for all of the constructive feedback. Your feedback has been extremely valuable and we request that as you begin your migrations, to continue to report gaps to developer support.

Thanks so much!

26 Likes
2

I really appreciate that the deadline was postponed. This is a major relieve for us. I also appreciate the steps that have been taken for a clearer and better communication. I hope that when the actual deadline nears we will have a more complete V2 api and that the path for migration will be clearer. Thank you for listening.

11 Likes
3

Hi @AshishShirode ,

A couple of months have gone by and I wanted to know if Atlassian had any new deprecation dates to announce.

I see that the v2 ticket queue is still showing as some ways away from 100% API parity, so I am wondering what vendors should expect over the next couple of months. Is the date going to be pushed until at least this fall?

6 Likes
4

They’ve only today added some options to fetch additional metadata (not quite an expand replacement): https://developer.atlassian.com/cloud/confluence/changelog/#CHANGE-1420

So that should yet again reset any deprecation date for ALL v1 endpoints by +6 months.

2 Likes
5

This signals a pretty big shift in the v2 design philosophy that could impact app/client architectures.

2 Likes
6

Hi @AshishShirode @HughWu or others:

I am glad to see the recent addition of “include-xxxxx” query parameters in CHANGE-1420. Are there plans to bring this change to custom content? (As well as possibly databases and whiteboards?)

If an application needs to be able to deal with all of the various primary content types, it is quite complicated if there are “shortcuts” to fetch this information with certain content types but not the others. For example, if “include properties” or “include operations” are available only for pages and blogposts, then developers still need to write and test the code to fetch these items separately anyway. This is no less work than before, operations become oddly slower for only one specific content type, and it introduces another code path that needs to be tested separately.

4 Likes
7

Hey folks :wave: !

Re: the include fields, I’ve started another post here so we can keep the discussions separate: New Optional Include Field Parameters in the Confluence Cloud v2 REST APIs

But to answer your question @scott.dudley - yes! We’re planning to bring the changes to more content types. We’ve released the change for pages and blog posts first so users can have a look and see if it fits their use case. Let us know of your thoughts in that thread.

Re: the deprecation dates, our team will be working through the next steps and will provide an update once we can provide a more accurate date.

5 Likes
8

Many of my Forge apps are broken because Atlassian has jumped the gun and deprecated @forge/ui-confluence on the assumption that v1 API endpoint access will be cutoff May 1st 2024. This has also broken the CLI linter and a few other issues I’m still attempting to bring to the attention of engineers at Atlassian (v12 to v13 below has more than only permission scope breaking changes).

@AshishShirode @HughWu what we need from Atlassian is to STOP any hint whatsoever of a deprecation date until v2 API parity for ALL endpoints is confirmed.

For the past 18 months there has been a 6 month deadline announced, followed by months of zero communication, and then as the timeline stress builds and developers flame the forums, Atlassian extends the date another 6 months. You’re doing this yet again.

This strategy (or lack thereof) is having compounding negative effects both internal and external.

eg below is a reply from Atlassian on my support ticket:

A few months ago, we rewrote the useContentProperty hook to migrate the usage of Confluence API v1 to v2 as Confluence said the V1 endpoints will be deprecated soon. This was included in forge/ui-confluence major version 13. This required an update to scopes as the v2 APIs use different scopes now.

This is also the reason why the latest version of the CLI has an error message about new required scopes.

To summarize, required permissions depend on the @forge/ui-confluence version.

  • version 12 and below - read:confluence-props and write:confluence-props
  • version 13 and above - read:page:confluence and write:page:confluence

Solution:

  1. You can continue using @forge/ui-confluence version 12 and ignore the lint errors in the CLI when deploying with forge deploy --no-verify but please note this is not recommended way.
  2. Update @forge/ui-confluence with npm install @forge/ui-confluence@latest --save and update scopes to use read:page:confluence and write:page:confluence

Below is from the changelog. Note that this changelog was posted Dec 12th 2023, while the OP on this thread was Dec 1st 2023.

The implementations of useSpaceProperty and useContentProperty hooks in @forge/ui-confluence major version 12 and lower contain deprecated Confluence V1 REST APIs. The version 12 and earlier versions of these hooks will no longer function after May 1, 2024 due to the public access removal of these endpoints.

@forge/ui-confluence major version 13 and higher contain a rewrite of the useSpaceProperty and useContentProperty hooks using Confluence V2 REST APIs. UI Kit apps using these hooks will need to update to new major version for their apps to continue to function as expected after May 1, 2024.

Behaviour and usage of the hooks between version 12 and version 13 will remain the same, however because the Confluence V2 endpoints require different permission scopes, changes will be required in the app’s manifest.

4 Likes
9

Hi @HughWu

Thanks–I’m glad to hear about more V.2 APIs rolling out!

It’s also been a couple of months since the above response about the V.1 removal from service dates, so I am wondering if there are updates. The top post on this thread says that it’s postponed “until at least June 2024”, which is now six weeks away. Is there an update? Or even if there is no fixed date to share yet, can we reasonably assume that we will get roughly six months after the date of whatever announcement Atlassian will eventually make?

Thanks,
Scott

4 Likes