RFC-19: Deprecation of Confluence Cloud REST API v1 Endpoints

General Request for Comments (RFC)
, , ,
7

Some things we have struggled with so far when switching away from the deprecated endpoints:

  • No way to get favourited spaces in v2 API
    • v1 API: /wiki/rest/api/space?favourite=true
  • No simple way of getting labels used in a space in v2 API
    • v1 API: /wiki/rest/api/space/{spaceKey}/content?expand=metadata.labels
    • In v2 API I would have to: Get pages & blogposts on a space → Then get labels separately for each page & blogpost, turning the one v1 API call in to huge amount of v2 API calls.
  • Get pages from space method of REST API v2 missing depth parameter
  • No way to get page authors in v2 API
    • Confluence API v2: How to get page authors information? - #4 by SimonKliewer
    • We use the logged in users permissions to make our requests against Atlassian APIs (ACT_AS_USER user impersonation), this ensures that we are not exposing data to users that don’t have the rights to view it. The suggested solution is to use our apps permissions to fetch this information instead of the users because the user might not have the rights to call the user search API. Wouldn’t that mean that we are circumventing Atlassian set permissions?
4 Likes
8

Thanks to @SimonKliewer and team for all of their hard work! Here are some points to consider:

1. Honoring Deprecation Timelines

I would like to suggest an adjustment of the deprecation dates to respect Atlassian’s six-month deprecation policies:

The post mentions that the sunsetting of V.1 content property endpoints will be delayed one further month (to Feb 1). If I read between the lines, the post implies that this is being done because the V.2 “Get content properties for (all entities of specified type)” APIs are not yet ready. I assume the goal is to sunset APIs only after the replacement has been available for the six month deprecation period.

I think this misses the subtlety that the V.1 APIs being replaced by the indicated V.2 content property endpoints are not, in fact, the V.1 “get content property” APIs. Rather, it is the deprecation of the expansions on general content fetches that are forcing developers to use those new V.2 APIs.

For example, I can currently fetch a bunch of entities along with their content properties in V.1 through GET /rest/api/content/XYZ?expand=metadata.properties.foobar. This no longer exists in V.2, so to avoid doubling the number of requests, we fetch all of the content first, collate the IDs, then batch up a request to receive multiple content properties at once through the as-of-yet unreleased V.2 content property APIs.

If you sunset the general GET /rest/api/content API in January but those content property APIs are not released until late this month, we have four months rather than six to implement the replacement. Perhaps it would make sense to standardize all of the API sunsetting and implement everything all at once on March 1? This also helps with the vacation issue previously mentioned.

2. Dogfooding

The post indicates that Atlassian will be removing public access to the V.1 endpoints, implying that Atlassian may still use those endpoints internally. Out of curiosity, are any projects within Atlassian dogfooding this work, and has it uncovered any gaps?

3. Whiteboards

Atlassian has rolled out an entirely new content type (whiteboards) that supports only the V.1 API.

How is this being integrated into the V.2 API work, and do we have a timeline? How can developers be assured of having reasonable time (and a reasonable deprecation window) to support this feature?

Even if whiteboards cannot be directly interacted with via the API, I believe they are now officially part of the content tree, so applications relying on only the V.2 API will need some way to deal with pages or other content types that have whiteboard ancestors or children.

If whiteboards are only supported in V.1 now and the V.2 replacement is not out until (say) October, this gives developers very little time to implement changes, and perhaps this too points to moving the sunset dates.

9 Likes
9

This is a really important point that has felt lost to me during this entire notification and enactment of the deprecation period. Despite being extended, the deprecation period clock has been ticking since the deprecations were announced, rather than once the replacement APIs were deemed both complete and stable.

5 Likes
10

Dear @SimonKliewer ,

thank you for your additional post.

Honestly I have no idea which of the comments/concerns raised by the community have been picked-up by Atlassian and if yes when it will be implemented. Wouldn’t it be possible to list all of them somewhere, give them a status and an expected time until they will be implemented?

Thank you

Andreas

1 Like
11

Would it be possible for Atlassian to add a response header indicating that a deprecated API has been used? This would make it much easier to detect where we are still using deprecated APIs when running our automated tests, and would lower the risk of surprise when the switch is eventually flipped to disable the deprecations.

This would be a huge benefit for our code base given that we share code between DC and Cloud and could instrument our tests to warn anytime such a header was observed.

7 Likes
12

For us the blocker to migrate to spaces REST API V2 is that we cannot get space labels / categories.
See Will there be a way to get space labels/categories in V2 API?

Kind regards,
Raimonds

2 Likes
13

Hi @SimonKliewer ,
Thanks for the RFC.
I must say that the indicated deprecation period is problematic. We tried to use some v2 endpoints, but not all replacements for v1 endpoints were ready. At this moment I’m lost with what is already working and what not, and we don’t have the capacity to try to migrate every couple of weeks.
The 6 month deprecation period should start once the v2 endpoints are stable.
Just last month the v2 format changed from integers for ids to the intended strings due to an Atlassian release error.

6 Likes
14

Why remove access to deprecated endpoints? The v2 endpoints are already versioned which is literally the point of versioning APIs.

And second other points in here regarding notification. Given that you’re blanket deprecating dozens of endpoints all at once, you should actively inform us developers now as to which of our apps are using deprecated v1 APIs.

1 Like
15

Second the comment from @nathanwaters. Why is Atlassian removing an API that works to replace it with an API that forces rework for all of your partners?

The v2 API as is will SLOW DOWN our existing apps because without expansions we are forced to make multiple API calls in series, with additional latency, authentication, error handling for each.

Simple things, like fetching a page, current version history and 1 named property can be done today in 1 round trip and return a response to the customer user. V2 API will force 3+ round trips. If the connect app services are running on a different continent than the customers ATL cloud instance we are adding 500ms+ seconds to every user response.

Forcing unnecessary rework by providing less functionality and lower application performance is not serving the Atlassian customers or partners best interests. Recommendation: Build a better v2 API that is compelling because of function and performance, and people will move to it.

Sincerely
Chris

6 Likes
16

@SimonKliewer Are you planning a replacement for the childTypes.* expansions? This is currently a blocker for us because we are showing a page tree in our app (similar to the tree in the Confluence side bar) and we need to know if a page has children without fetching the children to show the correct UI.

3 Likes
17

Thanks all for your feedback so far!

For the ideas brought up:

  • Atlassian providing some sort of tooling for vendors to be able to request a snapshot of their apps and corresponding deprecated endpoint usage → this is a great idea, we will investigate this idea and present our findings in the “Resolve” phase.
  • Adding a header to these endpoints to help developers understand when a deprecated endpoint has been used → Same as above!

For another theme that has been noted:

  • We acknowledge that in certain scenarios, the number of requests required from apps to fetch the same amount of content from V1 to V2 will increase. We are moving forward with this tradeoff for the reasons outlined in our blogpost here. However, we are confident this is a step in the right direction, and want to work with the community to make this transition as smooth and performant as possible. For example, the upcoming content property endpoints are a response to this concern → a new set of endpoints that will help cut down on the amount of calls required.

For other feedback:

@thomas2 Thank you for your input! This CONFCLOUD can be tracked.

@tobitheo Thank you for the feedback! With V2, we are sticking with more strongly typed endpoints, and along with this comes the distinction between pages and blogposts. This is a case where the count of calls with need to increase.

@MiikaMkiniemi Thank you for the comment! Re: favourited spaces filters - this CONFCLOUD can be tracked. Re: space labels - these CONFCLOUDs (labels on space, labels on space content) can be tracked. Re: Depth parameter - this is now addressed! Re: Page authors → Thank you for the explanation here! I am still working with an internal team to determine the best path forward here, and will let you know the consensus we come to!

@scott.dudley Thanks for the feedback here! I am currently working with the corresponding internal teams to get a more extensive update, but in the meantime I have created this CONFCLOUD for you to track its progress.

@andreas1 Thanks for the comment! Aside from the CONFCLOUDs linked above, here are the other two CONFCLOUDs we have open as valid migration blockers: CONFCLOUD-76295, CONFCLOUD-76347. These 2 tickets combined with the tickets linked earlier in the message round out all current migration blockers.

@raimonds.simanovskis Hi - the 2 linked tickets above for space labels can be tracked! Thanks for noting this.

@klaussner Thanks for the question! In the current state, you will need to use the child endpoints to check for child pages. In the future, we hope to introduce a set of endpoints that will return metadata of all children/descendants of a piece of content, regardless of their type, similar to how our ancestors endpoint works. But in the meantime, the recommended way forward is to use the child endpoints.

1 Like
18

Blog post and your reply don’t address why the need to remove access to v1 API.

It’s clearly not an immediate security issue. Your team needs a legitimate reason for such a large breaking change that will force 10s of 1000s of cumulative hours of unnecessary rework on developers.

Every competent tech company versions their API in order to allow the evolution of it while maintaining backwards compatibility and preventing breaking changes.

While Atlassian somehow can’t go from v1 to v2 without breaking every god damn Confluence app on the Marketplace, companies like Stripe version their API based on a timestamped date:

When a breaking change is introduced to the Stripe API, a new dated version is released. To avoid breaking your code, we don’t change your version until you’re ready to upgrade.

Whereas what you guys are doing here is rug-pulling developers, breaking their code and forcing countless hours of unnecessary rework to migrate to an inferior v2 API. This is precisely the type of non-technical bureaucratic middle-manager decision that Atlassian’s internal “flattening” was intended to stamp out.

The team behind the Jira API seem to be more concerned about developer experience considering both v2 and v3 APIs are still active and accessible. WTF is going on with the Confluence team?

How to encourage devs to migrate to v2 without f^^king them:

You keep v1 active, mark it as deprecated in the docs, stop adding new features and deprioritize support. You then add new features to v2, promote its benchmarked performance improvements and prioritize support.

If maintaining v1 becomes too much of an overhead, say five years from now, and there’s only a handful of vendors still using it, then it makes sense to do a forced migration.

–

Given the shitty siloed endpoints of the v2 API, is the GraphQL API at parity and not on the chopping block?

With the literal 100s of wasted hours you’re forcing on me, I’d like to build on a stable API that isn’t going to be rug-pulled in the future. There’s no point building with this new v2 API if you’re just going to kill access to it when v3 arrives.

3 Likes
19

Hi @SimonKliewer ,
You haven’t answered how the deprecation date of the v1 API fits with the v2 API not being ready.
In your answer you write:

We don’t know when these “upcoming” endpoints will be delivered, but we hear the existing endpoints are deprecated.
Deliver first, then deprecate!

5 Likes
20

@nathanwaters Incidentally, the GraphQL API is not available to Connect apps and I have not seen any feedback indicating that this is likely to change for the foreseeable future, so it is not an option for the majority of active apps.

3 Likes
21

Oh JFC. I had to search for your previous posts on here to verify that. Scott is correct; replies from Atlassian staff confirming it’s in beta and not available for Connect apps.

The GraphQL docs make zero mention of being unavailable for Connect apps. And the official v2 API blog post suggests using the GraphQL API as an alternative for removing expansions.

:man_facepalming:

Who do we need to escalate this to internally? I’ll take this to Mike and Scott if need be. I’ve already spoken casually to many long-time employees who’ve all agreed this is a poor transition strategy.

At the absolute minimum this deadline must be extended for at least another 12 months (and not Jan 1st ffs). I remember you guys started this v2 API by deploying broken IDs into prod where you switched strings for ints which were too long for JSON to parse correctly. Each time a new endpoint is released or a new gap/flaw is discovered, the migration deadline (if truly necessary) should be extended another 12 months.

Is the real reason for this access cutoff down to infra costs? v1 and v2 are running in prod in parallel now, so it can’t be a technical issue. Jira API has no issues serving both v2 and v3. If it is due to overhead costs then I’ve already outlined a suggestion on how to properly transition.

If this goes ahead I can foresee a substantial percentage of broken apps on the marketplace come Jan 1st, with cascading business impacts for vendors and customers.

Because any developer that migrates now is doing so knowing that the v2 API is still incomplete (just search “upcoming” in this thread). And any developer who rationally leaves this migration until Nov/Dec is highly likely to find missing data parity, and will need to roll the dice on Atlassian fixing that gap before the deadline.

Given that it takes 2 weeks to get a reply to a support ticket and the access cutoff date is stupidly set during a global holiday period, that’s a huge business risk.

And that is why you’re noticing intensifying anger from vendors on the forums. They know they need to action this unnecessary rework on an inferior and incomplete v2 API within the next 1-2 months.

7vzp1c

15 Likes
22

Thanks, @SimonKliewer. Endpoints like that would be really helpful. Ideally, we could get the number of children and descendants for a page (we are currently using CQL for that) and also for multiple pages at once (similar to the id parameter of the “get pages” endpoint).

23
24
25

Thank you everyone for your feedback! We greatly appreciate your inputs.

Firstly, we would like to express our gratitude to all the vendors who have already migrated to v2. We hope that you are experiencing the advantages of more granular and performant APIs. We are thrilled to introduce even more new endpoints to you as we introduce new content types in Confluence. Additionally, we are working on updating all Atlassian apps to use the v2 APIs.

We would like to take this opportunity to assure you that we are actively working on addressing every feedback item that we have received in previous community posts and as part of this RFC. We have created CONFCLOUD tickets for the feedback that was shared in the past and is currently in the RFC.

We understand that it can be difficult for you to identify all deprecated APIs used in your code. Fortunately, we have this information available and would like to offer you a one-time snapshot of all deprecated APIs used by your apps. To receive this information, please raise a Developer Support ticket and share your app key with us. We would be happy to provide you with a list of all the deprecated APIs currently being used by your apps.

We know that the holiday season can be a busy time for everyone, which is why we have extended the deprecation of all APIs until January 31st, 2024. We want to assure you that we are committed to following our policy as outlined in Atlassian’s REST API policy on time frames. If there are any gaps for a specific API endpoint, rest assured that we will only deprecate that endpoint six months after achieving parity for that endpoint. At the same time, we kindly request that you continue updating your apps to use v2 APIs as soon as possible so you can take advantage of their benefits.

Future Feedback: If you come across any gaps in REST API v2 in the future, please report them to Developer Support. Use the “Bug” request type and be sure to mention that gap is related to the v1 deprecation. We will actively work on resolving any blockers. This process is more transparent and your report will be added to the tickets queue. Going forward, we will not be monitoring the developer community for additional v2 feature gaps posts.

We appreciate all of you for working with us! Thank you so much for all your input and contributions that will make this a success!

1 Like
26