I would like to express my opinion on a missed opportunity that I believe exists in the Confluence v2 REST API.
I am puzzled as to why the space id and new version number are still required when editing a page. In my view, the version number seems unnecessary because it cannot be updated and must be incremented, so why must the developer provide it? Additionally, since the pageId is unique, why does the developer need to provide the space id?
These requirements appear to be cumbersome and unnecessary to me. Can someone please help me understand the reasoning behind these two items being mandatory when updating pages?
Thanks in advance!
Rick
Btw is the move to spaceId a hint towards spaceKey renaming?
Actually, providing the version number makes sure you update the right version when multiple clients connect in parallel. I acts as a kind of fencing token or lock.
Imagine the chaos if I read a page, someone else edits it, and then I update the page based on the (now) older version I’ve read earlier.
If someone/thing else edits the page simultaneously, the version number will increment and:
an app or script will need to check the latest version again, because it cant update it. But it wont analyze the updated content (maybe soon with AI), so its pointless from that perspective.
There is version history, so actually, it’s a safer bet as no conflicts will happen and you will be able to compare the multiple versions that were saved at once.
From the page editor, while you’re editing and someone saves a new version from the REST API, the page will update, but you can use ctrl+z to undo their changes and continue where you were.
In my opinion, there still isn’t a good reason to require a version number. However, if the version number were optional and you decide to provide it, the version number should be a condition. And if the page update then fails due to someone else saving in between, then it that make sense. Now it’s just cumbersome.
As Marc noted - the version number acts as a defense mechanism against accidental overwrites. This helps the client to be aware that they could be blindly overwriting content they had not yet read.
This is a good point above on the space ID requirement. I will check in to see if I can get this removed, thank you for your feedback.
Also - the move towards spaceId over spaceKey is part of a push to remove UGC from resource identifiers.
Hi Rick - thank you for the feedback here!