Deprecating many Confluence v1 APIs that have v2 equivalents

Hey,

This is a great suggestion, but unfortunately, we’d already started our comms process internally before this RFC process was announced. We’re taking in all the feedback in this thread, and encourage any developers to provide feedback they have, as we’ve already got some solutions on the way for problems presented here.

To your comment about multi-API surface area, unfortunately, with Cloud and Server/DC split, and the v2 API for cloud only, I don’t see a way around this. We don’t intend for you to need to develop against the GraphQL API unless you’d rather use it instead of the REST API. Your feedback is crucial for ensuring we meet all your needs with v2, so if you have any capability gaps migrating to v2, please let us know!

Hi,

Yes, we’re actively looking in to this and hope to have a fix deployed in the near future.

Hi David,

At this point in time, we don’t have any plans to migrate the base path to be consistent or offer the endpoints under that base path as well. There’s a technical limitation behind sharing this base path in Confluence that we haven’t prioritized tackling, as we’re currently focused on the API offerings themselves.

Hi,

For your specific cases:

  • Get content:
    • Finding out if pages have children (without fetching the children).

How are you fetching this information today with v1? Using the Get Content endpoint with the children.page expansion or the Get Content Children endpoint, or some other method?

  • Create content:
    • Creating a page as a child of an existing page.

We’ve prioritzed this already and will have it available shortly.

  • Get space(s):
    • Getting the space icon. (GraphQL only)
    • Finding out if the requesting user is a space administrator. (GraphQL only)
    • Getting a space by key.

We’re looking at providing space icon as an optional inclusion for the space endpoints. We’re also working out details on providing space permission/operation information (believe you’re accessing that through the operations expansion on spaces?). For getting a space by key, you should be able to use /wiki/api/v2/spaces?key=<key>

  • Get content for space:
    • depth=root parameter, which returns only the first level of pages in a space.

A way to do this is to use the Get child pages API: /wiki/api/v2/pages/{id}/children with the homePageId of a space.

  • Get space property:
    • Getting a space property by key.

You should be able to use /wiki/api/v2/space/<space-id>/properties?key=<property-key> to get this data.

We don’t have a public roadmap to offer right now for the v2 APIs, but your feedback has already been helpful in finding what to prioritize next.

2 Likes

Hey all,

We appreciate all the feedback here, and are already taking it into account for our next steps. We’ve prioritized some short-term actions we can take to fix issues presented in this thread, and will have more to share around this deprecation in the coming weeks. We do not intend to cut off access to v1 without parity in v2, so your comments here are extremely helpful in filling those gaps.

Thank you!

1 Like

The original title of this thread is “Deprecating many Confluence v1 APIs that have v2 equivalents ]”. The original post says these APIs will be deprecated in 6 months from (I assume) the date of the post.

We have established that there are a number of cases where v2 does not have equivalent calls. There are a number of points where Atlassian have said they will make changes based on requests, but that means vendors have (6-monthsToImplement) months to implement themselves.

Could we therefore change the action to again reflect the title and the intent of the first post? That is, either:

  1. Only start the deprecation for those APIs where an equivalent exists in production today, or
  2. Stop the deprecation period and re-start the 6 month count once all of the APIs have equivalents in v2
15 Likes

Dear @AlexWilliams

thank you taking our feedback into account. As @daviddrawio correctly indicated Atlassian should also consider adopting the deprecation period accordingly.

I’m not sure whether this is the right time but I’m a little worried about the changes I foresee for other endpoints especially the search endpoints in case you stick to the concept “just return minimum data with no expansions”.

To give a concrete example: in one of our apps we must collect the labels of all descendants which could be 1000 pages or more and we do that on the client side. For 1000 pages we currently need 4 calls in a row which takes approx. 1 second (250 ms per call). In case my fears become true and we have to collect the labels page by page this ends up 1000 calls and 42 seconds (!!) (1000 calls, 6 simultaneously due to browser limitations and 250 ms per call). Of course we could move that to the server side to overcome this issue but we tried the opposite for many years now - do everything on the client side whenever possible and now the pendulum strikes back.

To overcome this issue on your API side and stick to the concept you may want to consider allowing multiple ids to be provided per call for all endpoints.

Thank you

Andreas

1 Like

Hi @AlexWilliams ,

I appreciate all of the details, as well as the fact that you’re looking for ways to address the multi-entity use cases.

I do think, however, that there are many more corner cases of entity expansions that have not already been mentioned in this thread, but which will end up being performance-critical for various apps. The two issues I mentioned of “the new API has no way to do this” were literally the first two API conversions I examined in an existing app, and given the breadth of the v1 API and its expansion capabilities, plus other comments in this thread, I imagine that there must be others (potentially numerous).

I second @daviddrawio 's call to please rework the deprecation timetable to do a thorough assessment of what is truly available with the v2 API, and to adjust the schedule so that vendors actually do have six months to migrate, once equivalent APIs are made available.

The “we have no updates on GraphQL availability for Connect” issue is also a major concern, because it represents the only way to get expansion-like capability, and this API feature is unavailable for the vast majority of sophisticated Confluence apps (which are, ironically, the most likely to need it).

I understand that there are no updates as of yet on GraphQL. But would Atlassian agree that the absence of GraphQL support for Connect apps is likely to create performance problems? If so, can this be prioritized to get it done before the deprecation hits? Or, if this is another team, can you tell us which tree needs to be shaken in order to do so?

5 Likes

Thanks, @AlexWilliams!

How are you fetching this information today with v1? Using the Get Content endpoint with the children.page expansion or the Get Content Children endpoint, or some other method?

I’m using the childTypes.page expansion with the Get content for space and Get content children endpoints.

believe you’re accessing that through the operations expansion on spaces?

Yes, I’m using the operations expansion for that.

A way to do this is to use the Get child pages API: /wiki/api/v2/pages/{id}/children with the homePageId of a space.

This won’t work if the space doesn’t have a homepage. In that case, a space can have multiple child pages on the first level.

For getting a space by key, you should be able to use /wiki/api/v2/spaces?key=<key>

Thanks for the tip with the key parameter. I think that could work. However, we would still have to make two requests to get a property by space key: one for the space and one for the property itself because we need the space ID for the property endpoint. Switching to space IDs instead of keys will be difficult for us because we are referencing a lot of space keys in Forge storage items and there is no reliable way to updates these items when we switch to the new REST API.

We are seeing that all the ids in the REST API v2 are represented as int64s. This surprises us, as the main programming language that is used to develop applications using the REST APIs only supports integers up to 2^52. This means that the API can’t be used reliably in Javascript code in the frontend, Forge or ACE since we won’t be able to parse the value correctly.

Most of the Javascript applications will be using the default JSON.parse to convert the response from the API to Javascript objects. The next example shows what happens when we parse a response from the current v2 API:

JSON.parse('{"id": 9876543219876543}')

Object { id: 9876543219876544 }

As you can see, we won’t be able to get the right value from the API in Javascript.

This is a real problem as ids longer than 2^52 are already in use for content and space ids.

12 Likes

Umm. This isn’t the first time… Change notice - Connect - contentId value returned by AP.navigator.getLocation value changing from number to string - Confluence Development / Confluence Cloud Announcements - The Atlassian Developer Community

1 Like

I agree with the concerns raised by other about the content type specific endpoints and what that means for the aggregate performance and redevelopment required to support / migrate to them.

1 Like

Edit: some old timers at Atlassian have told me the v1 APIs used strings for a reason and that clearly the domain knowledge here has been lost internally. Ya’ll might want to reachout to some old timers this week.

2 Likes

@AlexWilliams why are the content properties V2 endpoints now using ids and not keys as in V1?

Get content property

GET /wiki/rest/api/content/{id}/property/{key}

vs

Get content property for blog post by id

GET /wiki/api/v2/blogposts/{blogpost-id}/properties/{property-id}

and

Get content property for page by id

GET /wiki/api/v2/pages/{page-id}/properties/{property-id}

Have I missed something, because I don’t understand the purpose of /properties/{property-id} if I have to call /properties to get the {property-id} and it provides the same information?

I’ll also need to load the properties, then search the array to find it by the key (which I know).

4 Likes

Different endpoints for pages and blogposts are a major concern for us also. We modelled our applications around contents, which allowed us to support pages and blogposts with the same implementation. Now we have to review every part of the code that uses a content identifier to add the information of whenever it’s a page or a blogpost. We used a layered architecture for our applications, assuming that contents could be identified by id. Thus, with this change, we are forced to alter code at every level of the architecture. We developed some utility libraries shared among applications that we will be also forced to change.

While this change will be costly, it will be possible to do it for operations that are sourced from iterations of the users in Confluence, as Confluence context or webhooks at least will provide us the type of the content. But we have a more complex problem to solve with ids that we have stored in the database. We already have thousands of content ids stored for scheduled operations. As the model that Confluence offered to us up to now was designed around contents, we only store the content id, and we don’t have any mean to know the type of the content.

5 Likes

@james.dellow , it does look like the v2 API has a direct equivalent to what you want for fetching content properties by key, which is this. This example works for spaces, but it appears also supported for the other endpoints:

/api/v2/spaces/${spaceId}/properties?key=${propertyKey}

This possibly gives you multiple results, but assuming there is no underlying change in the contract (meaning the property name remains a primary key and there are not multiple instances of the same property), you can just fetch the first answer out of the result list. At least if you have the spaceId, for which you may have to make another API call.

All of that having been written, it seems like an ID-based focus is not particularly helpful to most API consumers, and I do not see any circumstances in which we would be fetching properties by ID.

In case anyone missed it, while the page content property API is not (yet) deprecated, the space content property API is indeed part of the deprecation list, and all of the v2 endpoints for updating or removing properties seem to require the propertyId. I imagine this will be propagated to the other content types over time.

6 Likes

Ditto to some degree. And there’s no endpoint in v2 to simply fetch content by ID. So I guess we’d just need to hit blogposts/{id} and pages/{id} and go with whichever one returns a 200 response. Genius.

I wonder if anyone at Atlassian intends to address the fundamental flaws discovered in this thread or just steamroll on. The inability to JSON.parse IDs is the most hilarious one so far. I’ve pinged that to many internal Atlassian’s who’ve had a good laugh at that one.

3 Likes

I was thinking the same. Or use V1 search.

V1 search isn’t a foolproof functional replacement due to its “eventual consistency” nature. If you’re doing fast CRUD operations, you can’t necessarily expect search to be always caught up. This is especially the case if you’re (say) creating things from the back end, and then expecting to immediately see the same data from the front end. (I guess the requests end up on different database servers?) I once heard informally that the expectation for consistency was max 15 seconds, but I haven’t seen this published anywhere.

1 Like

Hi Nathan,

We appreciate your feedback. I can assure you there is no intention here to steamroll on and ignore feedback.

The team has been hard at work since this post was announced. We have been taking into consideration every piece of feedback posted here, as well as going over many tickets we have received.

We have already addressed a majority of feedback items received here and plan to release them in bulk next week.

We apologize for the misstep with the ids as strings, we were well aware of the issue with javascript ints, but when it came to the type used here we had it as a string and then accidentally changed it at one point as part of another refactor. This is one of the items that will be addressed next week with the addition of an id string field, and then a sufficient deprecation period.

8 Likes