What this is about
You change a file model with PUT or PATCH, like any model. Whether the content is swapped as well depends on one question: does the request carry a file whose name matches the file object?
The four cases
name changed? | matching file present? | Result |
|---|---|---|
| no | no | only own fields changed; content, size, type stay |
| yes | no | renamed; content, size and mimeType stay |
| no | yes | content replaced; fileSize, mimeType, fileVersion new |
| yes | yes | renamed and replaced; the file part must carry the new name |
Replacing the content
PATCH /api/rest/fileasset/update/f1…/upload
data: { "data": { "id": "f1…", "name": "Contract.pdf" },
"response": ["id", "name", "fileSize", "fileVersion"] }
files: Contract.pdf (new edition){ "data": { "id": "f1…", "name": "Contract.pdf",
"fileSize": 51877, "fileVersion": 1790000123456 },
"meta": { "error": false } }The fileId stays the same, and the new content lives in the same place. What happens to the old content is decided by the auditing of the model:
- the old content is kept as a version
- can be restored through a rollback
- see File versions
- the old content is overwritten
- cannot be restored through CDMS
Renaming only
PATCH /api/rest/fileasset/update/f1…
{ "data": { "id": "f1…", "name": "Framework contract 2026.pdf" },
"response": ["id", "name", "mimeType"] }{ "data": { "id": "f1…", "name": "Framework contract 2026.pdf",
"mimeType": "application/pdf" },
"meta": { "error": false } }The content lives under the fileId, not under the name. So renaming only changes one column in the database. mimeType stays as it was determined at the last upload, even if the new extension suggests something else.
PUT and PATCH
When: PATCH /update/{id} or /update/{id}/upload
You send only what changes. Without name in the patch, the stored name applies, and a file must then carry that name. With a new name, the file must carry the new name.
Result: Usually the best choice for files: rename, replace or both, without knowing the other fields.
When: PUT /update/{id} or /update/{id}/upload
As with every PUT, you replace the whole record. So send name and all your own fields along. The file must carry the name from the request. Without a file, the content stays.
Result: See Replacing with PUT.
Instead of multipart, you can also send the new content as Base64 in the field content. See Uploading.
Replacing concurrently
Two requests that upload new content for the same record at the same time would overwrite each other in the storage. That is why CDMS locks the record before it writes the content. The second request gets 409. Then read the record again and upload again. See Concurrent changes.
Pitfalls
What comes next
- Old states: File versions
- Back to an old state: Rollback for files
- Uploading in detail: Uploading