Uploading Files


This chapter explains how to upload files to the nnrestapi using pure JavaScript without any libraries.

If you are interested in finding out, how to create an endpoint that processes the fileupload, attaches the SysFileReference to a model and then persists the model in the database, please refer to the examples in this section

How to upload files with pure JavaScript


You can find a full example with fileuploads and JavaScript here: play on CodePen

Using mutipart form-data

Please refer to this section for detailled information on implementing the backend part of the file-upload.

By default, the nnrestapi will recursively iterate through the JSON from your request and look for the special placeholder UPLOAD:/varname.

If it finds a fileupload in the multipart/form-data corresponding to the varname of the placeholder, it will automatically move the file to its destination and replace the UPLOAD:/varname in the JSON with the path to the file, e.g. fileadmin/api/image.jpg.

Here is a basic example on creating a multipart/form-data request using pure JavaScript.

First, let’s create a simple form in HTML. As we are retrieving the input-values manually, there is no need to wrap the inputs in a <form> element:

<input type="file" id="file">
<input id="title" />
<input id="text" />
<button id="submit">Send<button>

<pre id="result"></pre>

And here is the JavaScript example using “VanillaJS” (nothing else but pure JavaScript) and FormData:

// put your url here
const url = 'https://www.mywebsite.com/api/index';

document.getElementById('submit').addEventListener('click', () => {

    const method = document.getElementById('request-method').value;

    const json = {
        title: document.getElementById('title').value,
        text: document.getElementById('text').value,
        image: 'UPLOAD:/myfile'

    let formData = new FormData();
    formData.append('json', JSON.stringify(json));
    formData.append('myfile', document.getElementById('file').files[0]);

    const xhrConfig = {
        method: method,
        headers: {},
        body: formData

    fetch( url, xhrConfig )
        .then( async response => {
        let data = await response.json()
        if ( !response.ok ) {
            alert( `Error ${response.status}: ${data.error}` );
        } else {
            document.getElementById('result').innerText = JSON.stringify( data );


If you select The result of the above example will look something like this:

    "title": "This is the title",
    "text": "This is the bodytext",
    "image": "fileadmin/api/filename.jpg"


The nnrestapi can automatically create a Model from your JSON-data and attach SysFileReferences (FAL) relations. Please refer to this example for in-depth information.