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?
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?
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.
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.
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.
@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.
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.
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.
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.
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.
This method of “… report them to Developer Support, use the “Bug” request type…” etc, especially the “We will actively work on resolving any blockers” sounded very good initially. I’d love to "log them, and then “watch, vote, and comment”, but it turns out that you can’t even get to this point very easily.
I want to share my experience with this, so you can add color and others can manage expectations.
We reported 3 important gaps on the 9th of October that are critical for us to move to v2. My expectation was that those will be added to the list ASAP, and we can rest assured that they will be worked on.
The reality is that those are still not added to the list. Ashish and his team are currently looking into those, trying to understand and recreate our use cases. This is fine, but not as a prerequisite for adding them to the list!
What I would like to express is that this sends the message of “instead of adding to the must-do list, we will first take a long hard look at your request, and if we can’t convince you to change it or dismiss your request in any way, then we will MAYBE add them to the list”.
Right now the process of reporting gaps leaves us with great uncertainty about the outcome and Atlassian’s real intentions.
I’m willing to look into “optimistic tagging” with support and the Confluence team. That would put your items “on the list” sooner, letting issue status convey whether the issues are “accepted” (ie understood and reproducible).
That said, when I put the tone of your post aside (on the assumption that we can address that by tagging sooner), I’m still left with your critique that our standard practices leave you feeling uncertain. So other than my superficial procedural fix, what do you recommend?
Please understand that closure is not an assertion that all questions or problems were addressed. My main concern is that we don’t fragment feedback in too many places, and that it gets to the right people. If there are outstanding questions please ask on the new topic. Or submit a v1-vs-v2 gap to developers support.