ACS - Unable to overwrite a document using REST API if versioning is disabled
As part of the ACS Hotfix version 126.96.36.199 an option was added in order to create documents through REST API without the "cm:versionable" aspect applied by default, this works with the parameter "versioningEnabled" set to "false".
The problem is that once a document is created without the versionable aspect it's impossible to overwrite the existing document using the REST API "POST /children" (https://api-explorer.alfresco.com/api-explorer/#!/nodes/createNode) even when the "overwrite" parameter is used, or "majorVersion" is set to true.
Steps to reproduce
Create a document using the "POST /children" REST API, with the "versioningEnabled" parameter set to "false"
The document has been created without issues
At this point perform another request to the "POST /children" REST API, with the same name, "overwrite" parameter set to "true", a comment and "majorVersion" set to "true"
As per the REST API documentation, the document should be replaced and the "cm:versionable" aspect should be applied (https://api-explorer.alfresco.com/api-explorer/#!/nodes/createNode) since i'm adding a comment and the "majorVersion" parameter is set to "true"
An HTTP 409 error is returned:
For simplicity i created a Postman collection with the two requests to replicate the problem (see attachment "DocumentOverwrite.postman_collection.json").
To reproduce you'll need to run the "create_node" request first and then the "overwrite_node" request.
From the discussion with the customer, here are details of their use case:
They are using an ETL from a partner which leverages the REST API under the hood. This ETL is ran multiple times so the first time nodes are creates and subsequent run only push new/modified contents. The ETL is not keeping track of what has been sync’ed before so it’s using the createNode API and adding the overwrite parameter in case the content has been identified as being modified between the 2 runs.
As mentioned in the description the API documentation states from day 1 the overwrite parameter only has an effect if the file has the versionable aspect.
Can we get clarification as to whether this is a strong design decision or something which we could reconsider in the future?
Taking a second look at the API-explorer documentation it seems this is actually working as designed:
Use overwrite to overwrite an existing file, matched by name. If the file is versionable, the existing content is replaced.
Maybe this needs to be more seen as an improvement?
From the discussion I had with the overwrite parameter in mainly meant to deal with the case where client wants to upload a file (thinking it’s a new file) while there is actually a content with the same name. In that case the client app can notify the user a file already exists and ask for confirmation of wether the file should be overwritten (in which case the createNode endpoint must be called with the overwrite param).
On the other hand for use cases where the client app uploads the first version of the file and then wants to change its content the updateNode endpoint is the best/most logical way of doing things. the first createNode call will have returned the id that can be reused in subsequent call… pure REST
As a potential workaround, you can use the Update Node Content API to update the node without requiring versioning.
You just need to know the ID of what you are updating.
FYI, I reproduced this in 7.0.
We should investigate if this exists in 7.0 and if it does look to develop a fix for Langley, then back port.