In terms of the deprecation deadlines, here’s another one:
The V.2 “get content properties for (contentType)” APIs have not yet shipped. The API that these components truly replace, as mentioned in more detail earlier, is in fact the generic GET /rest/api/content/{id}?expand=metadata.properties.xyz endpoint.
The RFC closing comment says that the deprecation deadline for everything is Jan 31, but that doesn’t seem like it can be quite right. For example, echoing what @klaussner wrote, we would expect a Mar 1 deprecation date for the above APIs, if the replacements were shipped today. The dozen tickets listed also implies that other areas of the V.2 API are not complete…so to which V.1 endpoints does that deprecation date apply?
If there are indeed going to be different deadlines for different endpoints, it gets confusing quickly with information scattered across forum posts. In this eventuality, as @bobbergman1 also suggested, could we please get a spreadsheet or whatever showing, for every endpoint in the V.1 API:
- the projected or confirmed date to sunset that specific endpoint
- the replacement V.2 endpoint(s)
- the ticket(s) on which the work depends, if appropriate, as well as any estimation of delivery dates
It would also be helpful to include the entire set of V.1 endpoints in this list, regardless of whether or not they are currently marked for deprecation. My assumption is that Atlassian would eventually like to deprecate the V.1 API in its entirety and that everything will move to V.2 at some point or another, and knowing whether certain non-deprecated endpoints are in the short-term or long-term backlog, or not being presently considered, would be helpful.
Building a document like this also helps to convey to the vendor community that Atlassian has a master plan for how all of this will work out, and perhaps the work of putting it together on an endpoint-by-endpoint basis might even expose dependencies that were not otherwise evident. It could even be combined with some sort of parity analysis as Nathan suggested earlier, so that this cycle does not need to be repeated in six months.
If Atlassian cannot treat the entire V.1 API with a single monolithic deprecation date, please also do not forget the issue above of different response object shapes (#8) and the pain that this causes vendors. One way to reduce this burden would be to set the deprecation dates for groups of endpoints rather than individual endpoints. For example, pages/blogposts might be one logical group, comments might be another group, and so on. (Those are just of the top of my head, and somebody needs to actually look at the response shapes to see what makes sense.) The downside is that you need to continue supporting the entire deprecated V.1 API group until the very last tiny blocker on any one of the endpoints is fully migrated…but it seems like this is exactly what Atlassian should be doing.
As an aside, I also don’t see a ticket for the promised “get content properties for contenttype” endpoint in the suggested ticket queue, so I hope it is still in progress.