Details
-
Improvement
-
Resolution: Fixed
-
Major
-
2.7
-
None
Description
The REST resources added in 2.7 carry @GET and @POST only, so a change is written once and never again. That makes one field of a change unreachable over REST: screenshots.
A screenshots value names attachments of the entry page, and those attachments cannot exist before the entry page does, because the page is allocated by the POST itself. So a client that wants an illustrated change has no order of calls that works:
- posting screenshots with the change names attachments that are not there yet;
- attaching first means creating the entry page itself, which is exactly what the endpoints exist to prevent — a page sitting at the next Entry### corrupts the numbering the next POST computes;
- attaching afterwards leaves no way to write the names, since there is no update endpoint.
The only way out today is to leave the release notes application behind and set the property through the generic XWiki object REST API, against the page the POST returned in reference. That works, but it asks a client to know the class and property names the endpoints were meant to hide, and it is two APIs for one change.
This matters for illustrated release notes in particular: a change about something visible in the UI is expected to carry a screenshot, so this is the normal path and not an edge case.
Proposed:
- A PUT on one change, addressed by the reference the POST returned, replacing it and answering the stored value the way POST does, and 404 when the change does not exist.
- The same for a release note, so that released and date can be set when the version ships — today a release note is also write-once.
Worth deciding as part of it: whether attachments should be reachable through the application's own API too, so that illustrating a change is one client flow rather than a detour through the generic API.