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