Today we’re announcing some updates on the timeline of removing deprecated v1 APIs from service. Our team is dedicated to ensure that the v2 APIs offer all developers a path to migrate their apps. We’re happy to share that since announcing this deprecation on Mar 1, 2023 we have made substantial progress in addressing bugs and gaps reported by this community. Over the past 6 months, we have also been working with several of you directly to resolve any blockers and have received feedback that many of you have begun or completed your migration. As a result of this work, the majority of Confluence API traffic now comes from v2 APIs. We thank you for your partnership here!
We recognize that there are still opportunities for further optimization and we will continue to make improvements to the APIs based on our internal testing and feedback from this community.
Given the reduction in developer reports and successful migration of most traffic, we plan to remove all v1 APIs currently marked as deprecated from service on December, 2nd 2024.
We ask those of you who have not yet begun to migrate to v2 endpoints to start doing so now. If you encounter any issues, please report them to developer support. We appreciate everyone who has already started their migration to the v2 APIs and thank everyone for the constructive feedback.
The v1 to v2 API migration is so poorly designed that the latest OpenAI deep-reasoning model released today cannot comprehend how to migrate code: https://openai.com/o1/
Go ahead, try and ask it to migrate this endpoint call: /rest/api/content/${id}?expand=space,history.lastUpdated
And of course Atlassian hasn’t provided any documentation or best practices on how to migrate such a call.
I have two questions about the REST API V.2 migration:
Rate-limiting
Can you please provide updates on how rate-limiting will be adjusted to accommodate the new APIs? Vendors have commented at length about how the V.2 changes will force one V.1 API call to turn into multiple V.2 calls, but it is unclear of what is being done here. I believe one of the earlier Atlassians working on this project mentioned that you would look into adjusting these limits.
The current rate-limiting documentation is fairly opaque and it does not actually describe what the limits are (nominal requests/minute and so on).
Would someone at Atlassian be able to explain what the current limits are and how these are going to be updated to support the increased volume of the V.2 API?
Status of remaining V.2 API gap issues
The official V.2 REST API gap list still has a dozen or so items outstanding. Can you elaborate on which issues are expected to be delivered and when (and perhaps update the status/resolution to reflect that)? I had been waiting on one of the items for over a year (CONFCLOUD-76475), only to be told a few months ago when I contacted support that it was probably not ever going to be shipped.
Wait, really? I’ve been waiting for this as well. According to this comment from May last year, the team is/was working on this endpoint, and in RFC-19 it was said to be “nearing release.”
There are even more feature gaps that aren’t tracked. For example, there’s still no or very limited support for folders and other new content types in REST v2 (see my comment on the folders RFC).
After taking a second glance, I misspoke regarding “never”. The exact response from Atlassian in May 2024 was:
We’re currently working on enabling retrieval of content properties for multiple entities at once but have run into some performance issues that we’re solving. Unfortunately, there’s no timeline yet for when it will be available.
and
The official rest-api-v2 label is indeed for tracking everything in our official backlog. However, it is not guaranteed that these tickets will be delivered depending on the ticket type.
For example, CONFCLOUD-76475 is a suggestion ticket and is technically not a blocker for v2 migration since it is possible to fetch content property information with the existing APIs.
…
We are currently investigating the feasibility of addressing the ticket to help reduce the amount of calls needed due to popularity of the issue. Beyond that, though, we can’t guarantee anything or give an accurate timeline on when this would be delivered.
I admit that I when I read these two quotes together (and see that the ticket is still unassigned), my brain automatically equates that to “never”. I would hope to be proven wrong, though!
We have to “hedge” with the statement, “it is not guaranteed that these tickets will be delivered.” It may not be possible to fix each and every bug, or it may not be economical. That said, I will take action on your overall ask about the status of remaining gap issues. I’ve opened VOC-5519 about this; unfortunately, that’s an internal escalation system, so you would need a TPM or Dev Support engineer to follow status.
Meanwhile, if they aren’t tracked, Atlassian will not consider them gaps. Laura already said this above, so for emphasis, please, report all gaps, as you find/learn them, through developer support as if they were bugs so they will get tracked, and most importantly tagged.
Reported gaps are being ignored. This has been the case for about two years now. Plenty of posts in the forums of people having their parity bug reports triaged and dropped.
This happens before a CONFCLOUD ticket is created. If one is created, the priority often gets downgraded, switched from bug to suggestion, and eventually dropped or ignored.
Developers were assured that there would be 100% feature parity before any 6 month deprecation date was set. This promise has been broken many times now.
v1 expansion queries are woefully absent or inadequate in v2. One call in v1 now requires multiple calls, and often exponentially more calls with abysmal performance.
Something as simple as uploading an attachment requires a v1 call while fetching that same attachment requires a v2 call. You can get/set content properties using the JS API but those exact same calls in the REST API are being deprecated and now require four calls instead of one. That’s the tip of the iceberg.
None of this makes any sense whatsoever. Most developers I know have held off migrating in the hopes that Atlassian would address these and the many major flaws.
I’ve started dumping every problematic endpoint I come across into a support ticket, but I don’t expect these will ever be fixed. I know I will simply be told “no, we’re not doing expansions for that” and a CONFCLOUD ticket will not be created. No ticket, no gaps lol.
eg I’m staring at this v1 call right now trying to workout how to possibly fetch the same data in v2 without needing to make 100s of calls to replace it: /rest/api/content/{id}/version?expand=collaborators.users
Thanks, @ibuchanan. I’ve reported this as a bug through developer support, but I only realized that the feature gap wasn’t being tracked when I went through the list of issues that Scott posted above. Since Atlassian staff has mentioned in the RFC that v2 APIs for folders will be made available soon, I assumed that the issue was already tracked somewhere.
As expected, I’ve reported multiple problematic endpoints that lack feature parity. None of them are being turned into CONFCLOUD tickets, so those gaps will not be tracked.
If one call now requires 100s of calls to get the same data, I would very much consider that to be a parity gap.
Edit: after pushing for it, I managed to get two CONFCLOUD tickets created. They’re tagged as “suggestions” though so I suspect they will never be implemented.
So when using AP.request() if you don’t do .replace(/^\/wiki/, '') on each next link you end up with a 404 because it tries to call /wiki/wiki/api/v2/[...]
I also stumbled over this one. One explanation could be that v2 makes it right by being relative to the host (which is [company].atlassian.net) as per the leading slash, not the Confluence base. A hassle nevertheless. Appreciate your persistence.
I can only agree here. AP.request will fail when using the next cursor which is not acceptable. @ibuchanan: will Atlassian fix this or de we have to work around this?
The problem with all of this is that if they ever get around to fixing these flaws, it will break the API and whatever workarounds developers have built to consume it.
This is why most companies at Atlassian’s size (and really any modern tech company) will deploy APIs with timestamped versions. eg either a query parameter or header with a specific date like "Stripe-Version: 2024-09-30.acacia"
Developers on Stripe can still use an API version from 13 years ago and not be worried about it breaking. Atlassian goes from v1 to v2 and everything breaks, and then continues to have ongoing breaking changes.
Ok, so pagination has completely changed again in v2 API endpoints. Every developer on this godforsaken platform will now need to keep an eye out for that rollout and check their entire code portfolio for impacts.
Hi @LauraMehrkens is there an updated timeline? there are still 20 unresolved Issues related to v2 feature parity in this list
And there are even 3 Issues IN PROGRESS in that list, we are waiting on resolution for two of those 3 In progress Issues.
We’re extending the deprecation period for all Confluence v1 APIs currently marked as deprecated until Monday, March 31, 2025. This is to align the deprecation of v2 APIs with the deprecation of UI kit 1 and associated scopes. On Monday, March 31, 2025 all Confluence v1 APIs currently marked as deprecated will be removed from service.
To provide more clarity on v2-related requests, we have updated the status of all remaining tickets to reflect our plans to action them. In summary, tickets marked as:
‘Gathering Interest’ may be implemented before March 31, 2025 but we are not guaranteeing this as we don’t consider these requests to be blockers for migrating to v2 APIs. If your app is dependent on any of these requests in order to migrate to v2, please describe your use case in the comments by December 13, 2024, so our team can further review the requests and revisit our implementation timelines. We will share an update on these requests on December 20, 2024.
‘Future Consideration’ will not be implemented before March 31, 2025, unless we have more evidence that these are blocking your app from migrating to v2 APIs.
@LauraMehrkens Thank you for the update. Maybe I’m reading your post wrong, but “for the following Confluence v1 APIs currently marked as deprecated” for me indicates the extension only applies to a subset of the v1 endpoints in question? Or does the extension apply to all v1 endpoints that were (so far) marked for removal on December 2?
(I see the changelog entry has already been updated with the new date, which indicates all endpoints listed there are covered.)
Also, (when) will the Warning response headers for the affected endpoints be updated? Currently, it still says 299 - "Deprecated API, will be removed on Mon, 2 Dec 2024 00:00:00 GMT at least for the v1 /content/{id} endpoint.
Hi @heinrich-wikitraccs, I just corrected my post. The extension applies to all Confluence v1 APIs that were previously marked for removal on Dec 2. Thanks for catching this!
Also, (when) will the Warning response headers for the affected endpoints be updated? Currently, it still says 299 - "Deprecated API, will be removed on Mon, 2 Dec 2024 00:00:00 GMT at least for the v1 /content/{id} endpoint.
We will update the Warning response headers next week.