Uploading Files

Warning

This example uses an JavaScript with a very "old" way of creating and sending XHR-requests.

You will only need this, if you are still forced to optimize for Internet Explorer 11 and below.

For a more modern approach we would recommend using the promise-based fetch() or a library that saves a lot of headaches like Axios

Hint

This chapter explains how to upload files to the nnrestapi using pure JavaScript without any libraries and shows a solution that is compatible with browser not supporting ES6+ and fetch() like Internet Explorer Version 11 and below.

If you are interested in finding out, how to create end 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 for older browsers

Tip

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
var url = 'https://www.mywebsite.com/api/index';

document.getElementById('submit').addEventListener('click', function() {

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

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

    var xhr = new XMLHttpRequest();
    xhr.overrideMimeType('application/json');
    xhr.open('POST', url);

    xhr.onload = function () {
        var data = JSON.parse( xhr.responseText );
        if (xhr.status != 200) {
            alert("Error " + xhr.status + ": " + data.error );
            return false;
        }
        document.getElementById('result').innerText = JSON.stringify( data );
    };

    xhr.onerror = function () {
        alert('Some other error... probably wrong url?');
    };

    xhr.send(formData);

});

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"
}

Tip

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.