Uploading

What this is about

A file reaches CDMS in one of two ways:

• Multipart: the request consists of several parts. One part is the JSON, the others are the files. This is the normal way, especially for larger files.
• Base64: the file is text inside the JSON itself. This is convenient for small files, for example from a script, but it is about a third larger than the file.

The same rule applies to both: the file part and the file object in data find each other by name.

Multipart

The /upload endpoints expect multipart/form-data with two kinds of parts:

POST /api/rest/fileasset/create/upload
Content-Type: multipart/form-data; boundary=XYZ

--XYZ
Content-Disposition: form-data; name="data"
Content-Type: application/json

{ "data": { "name": "Contract.pdf", "title": "Framework contract" },
  "response": ["id", "name", "mimeType", "fileSize"] }
--XYZ
Content-Disposition: form-data; name="files"; filename="Contract.pdf"
Content-Type: application/pdf

…bytes of the file…
--XYZ--

{ "data": { "id": "f1…", "name": "Contract.pdf",
            "mimeType": "application/pdf", "fileSize": 48213 },
  "meta": { "error": false } }

The server has set mimeType and fileSize. It does not evaluate the Content-Type of the file part; the file type comes from the extension of the name.

In the browser you build such a request with FormData:

const form = new FormData();
form.append("data", new Blob([JSON.stringify({
  data: { name: file.name, title: "Framework contract" },
  response: ["id", "name"]
})], { type: "application/json" }));
form.append("files", file, file.name);
fetch("/api/rest/fileasset/create/upload",
      { method: "POST", body: form, headers: { Authorization: "Bearer " + token } });

append data as a Blob with type application/json,
the file under the part name "files",
and do NOT set the request's Content-Type yourself:
the browser adds the boundary.

Base64 in the JSON

Instead of a file part, you write the content into the field content of the file object. This works on the normal JSON endpoints POST /create, PUT and PATCH /update/{id}:

POST /api/rest/fileasset/create
{ "data": { "name": "note.txt", "title": "Note",
            "content": "SGFsbG8gV2VsdA==" },
  "response": ["id", "name", "fileSize"] }

{ "data": { "id": "f2…", "name": "note.txt", "fileSize": 10 },
  "meta": { "error": false } }

content may also come as a data URL, that is with a prefix such as data:text/plain;base64,. CDMS cuts off the prefix. content is only read for the upload and is never stored or returned.

Several files and nested files

A request can carry several files, including for file models that hang as children on another object. Each file finds its object by name, no matter how deep it sits in data:

POST /api/rest/dossier/create/upload
data:  { "data": { "title": "Dossier 1",
                   "attachments": [ { "name": "first.txt" },
                                    { "name": "second.txt" } ] },
         "response": ["id", { "field": "attachments", "response": ["+"] }] }
files: first.txt   (file part)
files: second.txt  (file part)

The dossier and both attachments are created,
each attachment with its content.

For this, models without a file of their own, like the dossier here, also get the /upload variants. As always, the child needs the CREATE flag on the relation. See The four cases in nested writing.

The flow

The content only becomes current once the database has committed. If the request fails before that, it is discarded. More on this in Files and transaction.

When it does not match

Pitfalls

What comes next

• Swapping the content: Replacing and renaming
• How large a file may be: Size limits
• Fetching the file again: Downloading