Short answer, yes. To the extent that our extensibility standards team can propagate the learnings from this Confluence deprecation to all teams.
4 Likes
Good news. I really appreciate that. These little things make a lot of difference. Thanks for listening and taking the time to respond.
So they’re doubling-down on this unnecessarily complicated transition plan to bulk deprecate dozens of endpoints one-by-one on varying dates?
Rather than migrate an app in one go, we’re all going to be forced to migrate over 12-24 months as each endpoint slowly reaches parity. Miss one of those dates scattered throughout the calendar year and your app stops working.
1 Like
Hi @tpettersen,
It’s been a couple of weeks now and I was wondering if any updates were available in general? Also, the previously-promised “get multiple content properties for contenttype” endpoint still has not shown up in the public API and I was wondering if this is still set to be released soon? (It’s a blocker on this side.)
Thanks,
Scott
5 Likes
@tpettersen I was wondering if a vendor can ask Atlassian to provide the list of endpoints in use, then why do we have to also open tickets to ask for the v2 API implementation of those endpoints? To me it looks like Atlassian already has the list of endpoints needed by vendors, they just need to go through those. Why is an extra round of back and forth required?
4 Likes
Jumping in since Tim is currently out-of-office.
The summary reason is the change from v1 to v2 is not strictly 1-for-1. Some of what is being addressed in the change are fundamental problems in the design of the v1 API.
One side of the problem is that continued use of an endpoint is not a clear signal that there is a blocker. We’ve done our best to get the news out but we know there are app developers who (to their own disadvantage) don’t read community posts, changelogs, and may miss the deprecation header.
Another problem is that knowing the fact of a v1 usage may not be sufficient to know your technical design intent. Even though our logging tells us which endpoints are in use, that’s not a full picture. We intentionally remove user generated content (mostly whatever is a variable in the OpenAPI spec) which can leave us with an incomplete picture about how you are using an endpoint.
It boils down to the deductive abilities of our Confluence developers. They have already used existing endpoints and the data from logs to project what is needed in the v2 API. Based on that analysis, they believe the coverage is already complete. So, for the Confluence team, the remaining gaps aren’t a simple matter of missing endpoints but a subtle set of surprising usages of the v1 API.
Hey @ibuchanan - thanks so much for the response here.
I just wanted to clarify something about endpoints versus functionality on those endpoints. When you say this:
Are we talking about whole endpoints only, here, or are we also talking about properties which those endpoints return?
As an example, one of the biggest blockers for me and my team is the fact that we’re unable to easily pull a list of all of the labels on a given space, which is one call in V1, but would be a completely manual process in V2. There’s an official issue for it already, and in theory it’s being worked on, so that’s fine - but to me I’d be surprised if that use-case was… surprising. I can’t speak for what others are blocked by, but this is the one that stands out to me.
I can understand the move from 1-2 not being a complete 1:1 with endpoints - that makes sense. But when you say that the team believes coverage is more or less complete, are we talking about about the list of endpoints in general, or does the team believe that their coverage of all of the properties/functionalities of those endpoints is essentially complete as well?
3 Likes
Yes, I meant the parameters, in the OpenAPI sense which appear in paths and query strings, that affect how the resource is rendered and used by Apps.
RFC-19 was an assertion of both endpoint and functional coverage, and an ask to point out gaps, which are now being tracked as CONFCLOUD bugs.
Reading CONFCLOUD-76344, I can see your point. From the set over which I was more aware, I had observed more subtle interactions, like where expand was used to cleverly organize content & metadata. In redesign, those concepts are intended to have a cleaner split. Perhaps that’s why this straightforward query of labels was overlooked: it’s not exactly surprise (which was my choice of words) but maybe a complexity with an unclear solution in the new design paradigm?
In any case, I’d like to understand the underlying assertion that @JordanBurrows and @levente.szabo are making here. I was merely explaining our reasoning, but maybe we’re wrong? Are the gaps so numerous and apparent to you both that we should be looking closer at the “hold out” usage of v1 APIs? Are we talking about 1 or 2 endpoints, a dozen, more?
Hi @ibuchanan
Due to the new API not being a 1:1 replacement (particularly with different concepts, primary keys and object shapes), it is difficult to partially migrate to the V.2 API while leaving other calls with V.1.
From a shipping-in-production perspective, I am a 100% holdout on all API V.2 endpoints without exception. This is because not all of the APIs I need are available yet, and existing V.2 migration work will stay on a branch until everything can be migrated. If other people are following similar models, you aren’t necessarily going to find any smoking guns in current endpoint usage stats.
To put it more directly, it’s hard to swap out only one API call without also swapping out all of them. As mentioned above, doing a partial lift of the API means juggling between different, incompatible shapes and PKs at various points in the app. While this is not completely impossible to manage, it generates a lot of throwaway work, and it increases risk and testing burden. It would be so much cleaner if we could just do the migration when everything is ready.
Unfortunately, the clock is ticking while we are waiting for these remaining APIs to be implemented, without any clear guidance as to delivery dates for promised or in-progress endpoints. We don’t really have any updated guidance on how receptive Atlassian might be to extending that deadline either, or making it per-endpoint, although I am hoping that we will see more once Tim gets back from OoO.
As I think I have also mentioned before, the question of sufficient API coverage also needs to take performance into account. Even if the new V.2 APIs have theoretical 100% coverage of V.1 features, this doesn’t work in a practical sense if the equivalent V.1 paradigm takes 500+% longer to execute on V.2.
8 Likes
Yes. This confirms my point that using a v1 API is not a clear signal for that endpoint; hence, we could not open bugs just because they continue to be used.
I want to second everything @scott.dudley is saying. This is a very challenging migration to juggle for all the points already made above and elsewhere, and most of the well-articulated individual points and questions posed at the beginning of this thread have still not been responded to by the Confluence team (despite a number of promises to do so!).
We’ve also been waiting patiently for some equally articulate and clear answers to these questions, as well as statements on the status of the target dates deprecations and removals (and even whether the dates will be per endpoint or as a group). The radio silence is frustrating to say the least.
5 Likes
Thanks so much for the quick response @ibuchanan!
I can’t speak for any other developers here, so I can’t confidently speak to the number of gaps overall. But, I can share my experience in developing a brand new app on Confluence’s API. Unlike a lot of others here, there’s actually no migration that I needed to do here - I was building a new app from scratch, and decided “hey, if there’s a V2 API, why would I go with V1? Let’s just go with the new thing immediately” - and so I tried.
The first iteration of that app is really simple. I’m really only reading pages and spaces and transforming some data. At this point I’m not creating or updating anything - really only reading, and there were a couple of places I ran into difficulty as I did this. Three were, IMO, reasonably big problems:
-
The first was the label issue I mentioned - I’ve already talked about it in a few places in this forum, so I won’t put it all here again, but basically the workaround in V2 for getting all unique labels in a space would be iterating through every page in the space, getting all the labels, and de-duplicating - which is obviously a huge amount of calls for no reason. To me this feels like a pretty common, baseline thing I’d expect to be able to get in one call.
-
The second was the formatting on the page body. The documentation is (well, was a week or two ago) inaccurate here - it says here that I should be able to specify a number of different body formats, and at least a few of them don’t actually work - the API considers them invalid. I commented earlier in this thread about that. In my case in googling around for what I needed, I was recommended to use a format that no longer appears to be supported. This wasn’t a blocker for me, because I found one (“view”) that seemed to give me what I wanted, and does work, but still, the docs weren’t accurate there.
-
The third was no apparent way to get usernames or emails or anything identifying out of an authorId in the Confluence API itself. I haven’t put any emphasis on this one in my feedback though, because I understand that this was a conscious choice for privacy/security, etc. But, worth noting, it IS inconvenient when I want to show the name of a user who published a page - I functionally can’t do that, it seems.
Since the app I’m building is new and simple (for now), I’ve really not dug deep into what was previously possible with expansion, or things like this that have been changed/removed; I’ll leave that to the other folks who feel they’re blocked from migrating. But running into those two things while building my tiny app definitely does shake my confidence a bit in terms of continuing to build on V2.
FWIW I actually quite like V2’s approach in general, and it’s felt simple and nice to use - there are just a few gaps at the moment.
4 Likes
Wild.
2 Likes
@JordanBurrows yes I’ve been also working on a new app the last months and it was difficult to not use V1 to say the least. The V2 endpoints are very incomplete and still lack many features as is evidence by the comments on this thread and in other posts.
It’s just very hard for me to understand how we can rush to a new API version when that API version is clearly incomplete. The logical approach, at least from the outside, would be to finish development of V2 and then deprecate V1.
As I’ve said before this is very dissatisfactory and frustrating.
6 Likes
Thanks, @ibuchanan for the additional details.
Another thing I am confused about (again) is whether all v1 endpoints are targets for deprecation eventually, and we should be reporting v1 endpoints we currently use but not marked for deprecation yet or just the once mentioned here?
In other words, is the long-term plan to remove the whole v1 API from service or just specific endpoints but keep the rest alive?
I see that @scott.dudley also mentioned this and suggested communication about all v1 endpoints in this comment, but received no response. Correct me if I missed it.
4 Likes
Hi @tpettersen and @ibuchanan
It’s been another couple of weeks and I was wondering if Tim might be back in the office and could provide updates? Or, if not, perhaps someone else on his team might be able to pick up the ball?
Thanks!
6 Likes
Hi all!
For us it would also be important to know if we should plan to migrate completely away from REST v1 endpoints in near future.
Our current status is that we have a working implementation for our app using REST v2 endpoints and some REST v1 endpoints that have not been marked deprecated.
But we’re facing significant performance issues that we think are not solvable without some changes from Atlassian side. Even greatly increasing the amount of concurrency in our REST API usage does not give us performance that would be on par with our REST v1 implementation.
Allowing some simple expansions in the REST v2 bulk endpoints would go very far in solving our performance challenges: for example being able to expand labels and content properties when fetching pages of a space.
Cheers,
Riku
8 Likes
To give more context: we’re currently running into rate limits with the REST v2 implementation of our app (429 responses). That is why I think that we cannot further improve the performance by just making more calls concurrently.
Another dimension how Atlassian could help to solve our performance issues would be to make sure that the rate limits for the REST v2 endpoints are very high.
4 Likes
Would like to add one more to the list:
There seems to be no intuitive way to update a page or blogpost labels in v2.
In v1, we are able to specify an array of labels during Update Content (deprecated).
However in v2, it seems like I would need to do these steps in order to update a page/blogpost labels;
- Get all labels for a page/blogpost using v2 GET labels for page/blogpost
- For each label retrieved above, do a v1 Remove label from content using query parameter
- Finally, do a v1 Add labels to content for labels that I want to update.
I would have to make a minimum of 3 API requests just to update a label for a page.
Let me know if there’s a relevant topic for me to raise this 
The resolution for RFC-19 explains how anyone in the community should raise a specific gap:
I realize this does not address some of the other concerns raised in this thread about pace/timing of the deprecation, if not other aspects of our ecosystem policy. I am continuing to work with the Confluence team to try to get answers. But please do not let that uncertainty get in the way of logging specific gaps. In the RFC, the Confluence team has already committed to closing the gaps as tracked in CONFCLOUD. I know that I so often say, “please watch, vote, and comment” about issues, but this case already has “special dispensation” for those issues with the rest-api-v2. So please log them, and then “watch, vote, and comment” to deepen the understanding and improve the prioritization.
4 Likes