Best practices for v2 API migration?

Confluence Development Confluence Cloud
1

This migration is horrific, even by Atlassian standards.

Every endpoint I’m looking at is going from one call to three or four.

Where are the migration guides and best practices?

eg endpoints like this:

  • /rest/api/content/{id}?expand=space,history.lastUpdated
  • /rest/api/content/{id}/property/{propertyKey}
2

For the content property one, as far as I can tell this is the migration:

v1 API:

  1. GET /rest/api/content/{id}/property/{propertyKey}
  2. PUT /rest/api/content/{id}/property/{propertyKey} with incremented version number.

Done. That will create or update the content property.

JS API:

AP.Confluence.getContentProperty() and AP.Confluence.setContentProperty() don’t appear to be deprecated at all. They do the exact same thing as the v1 endpoints above. Completely mindboggling.

v2 API:

  1. Get the content type either via AP.context.getContext() or POST /api/v2/content/convert-ids-to-types
  2. Assuming it’s a page, now you need to find the propertyID via GET /api/v2/pages/{page-id}/properties?key={propertyKey}
  3. If it doesn’t exist you need to hit POST /pages/{page-id}/properties to create the property
  4. If it does exist you need to hit PUT /pages/{page-id}/properties/{propertyID}

That’s one endpoint. Similar story for almost every other deprecated endpoint. This all seems so dumb that I feel like I’m missing something.

1 Like
3

To be fair, you also have/had to distinguish in v1 whether a property already exists and make a GET request to find out the current version, followed by a PUT or POST request for the update.

But I agree that the new APIs complicate things a lot, especially when you have used v1 expansions. There are many situations where you need to make N+1 requests, and achieving acceptable performance is not trivial. I have been using dataloader for batching and caching to reduce the number of requests, which has worked pretty well so far. You are also going to have to parallelize requests as much as possible.

1 Like
4

Yeah you needed to GET to find the property version number, then increment that in the PUT update (I’ll edit that in). But there are three major changes:

  1. You need to find and use a particular content type
  2. You need to lookup and use a propertyID instead of just using the propertyKey
  3. You need separate POST and PUT requests

These changes are all so absurdly complicated that I would expect Atlassian to provide individual migration guides for each endpoint deprecation.

And when I’ve asked about how descriptor display conditionals work with these changes I’ve been told that actually nothing at all has changed with content property keys in regards to storage. So on Atlassian’s end nothing has changed, they’ve just made it far more complicated for developers to use them.

On expansions I’ve got no clue how to replace them other than hitting about a dozen API calls to fetch whatever data was previously returned in v1. For that use case there is zero v2 parity or any migration guides whatsoever.

1 Like
5

Dear @nathanwaters

Yes, the entire v2 story is, to use a modern term, quite “weird.” The targets seem questionable, and the implementation leaves much to be desired - examples are below.

We’re still going through the same struggles you’re facing.

Don’t give up.

Best,
Andreas

Targets:

  1. In case better segmentation of permissions was the target => this could have been solved with much less impact
  2. In case better performance was the target => in case there is a benefit on Atlassian side the multiple calls we need to make (in a row!) on our side nullify this advantage - all our apps are significantly slower with v2

Implementation:

  1. friendlyDate has been dropped but the user details till don’t contain the locale
  2. pages and blogposts contain the authorId on the top level, comments in the version
  3. You can get custom content below pages and blogposts at least containing some basic details with the respective calls, but for custom content below custom content you can only get the ids and have to move on from there
  4. The “include-xyz” parameters added later are only available when you get one single page, blogpost etc. but not when you want to collect multiple pages, blogposts.
  5. When getting an attachment you either get pageId, blogPostId or customContentId. The proper approach would have been to include a container object with one id and one type.
  6. …
3 Likes
6

I’m looking at Confluence attachments now:

  • To upload: I must use v1 API
  • To fetch: I must use v2 API

:roll_eyes:

7

And who needs https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-comment/#api-footer-comments-get without any filter? All similar endpoints allow the specification of ids or other filters but this one simply returns all comments from all pages in all spaces. Interesting…

I was only looking into it because https://developer.atlassian.com/cloud/confluence/rest/v2/api-group-comment/#api-custom-content-id-footer-comments-get stopped working here.