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.
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?
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.