Publish and Retrieve Images and Files with REST

Last modified: August 20, 2024

Introduction

This guide covers how to use REST to send and retrieve files, including images, in Studio Pro.

You will learn about the following:

Creating a REST service from a System.Image or System.FileDocument entity
- Trying out, or testing, the service
- Setting the MIME type for supported files
Retrieving files with REST

If you are only interesting in consuming files, you can skip down to the Retrieve Images and Files with REST section.

Prerequisites

To publish or retrieve files with REST, do the following:

Install Studio Pro

Mendix recommends reading the following for some more background:

Publishing and consuming REST services
Working with Images, Videos, and Files in Studio Pro

Send Files with REST

Imagine that your app is functioning as a content management system (CMS), and you want to be able to send and receive images and files. You can publish the generalized entities as a REST service, which exposes the binary data of files stored in the entity.

Publishing the Service

To publish the System.Image or System.Filedocument entities as a REST service, do the following:

Add a new module (or use MyFirstModule) and name it CMS.
Go to the domain model and create a new entity called MyFile.
Add a System.Image or System.FileDocument generalization to the MyFile entity
Generate the overview pages for the file or image entity, then link them to the home page and navigation.
- Right click on the System.Image or System.FileDocument entity that you want to publish, and click Generate overview pages.
- Add a button to the home page that links to the Overview page you created.
Expose the entity as a REST resource.
- Right-click on the System.Image or System.FileDocument entity that contains the file(s) that you want to publish, and click Expose as a REST resource.
- Click Select next to the Service field, then click on the folder where you want to create the service and click New. Enter a name for the REST service and click OK.
Back in the Generate resource and operations window, select MyFileID as the Key attribute and check the boxes for the following Operations*:
- Get all
- Get by key
- Post (Create)
- Delete
See the Operations section of Generating a Published REST Resource for a description of each operation.
Click OK.

The Published REST service document for the exposed image or file entity has been created and is now open on your screen.

After you run your app, click the URL in the Location field to view the OpenAPI specs.

Understanding the Service Details

Open your published REST service, then double-click the Get by key, or single-click and click Edit, to open the Get by property details. By default, the Get by key will return a binary response. The Export mapping is blank because a binary object without an export mapping returns binary content.

Click Show next to the Microflow field to view the MyFirstModule.MyFile_Get_ByKey microflow. The generated Get by key returns a file document.

Adding the MIME Type to a GET Microflow

A GET request to the REST endpoint you created (in this example, http://localhost:8080/rest/cmsapi/v1/myfile/1) will return the binary for the first uploaded file. We need to specify the expected media type so that it returns the file in the expected way (for example, displaying an image).

In the GET_ByKey microflow, specify the media type (or MIME type) in the content headers. To learn more about content headers in microflows, see the Return a file document entry in the Microflow section of Published REST Operation. Detailed steps are explained below.

See Common MIME types for a generic, external list of common content header types.

MIME Type for Images

In the GET_ByKey microflow, do the following:

Drag a Create Object action into your microflow just before the End Event.
In the Entity field, select System.HTTPHeader.
Under the Refresh in client field, click New.
Set the three drop-down options to the following:
- Key (String (Unlimited)) – set the Value to 'Content-Type'
- Value (String (Unlimited)) – set the Value to 'image/png', or the image type that will be returned
- System.HttpHeaders (System.HttpMessage) - set the Value to $httpResponse

MIME Type for PDFs

Follow the steps in the MIME Type for Images section, then set the three drop-down options to the following:

Key (String (Unlimited)) – set the Value to 'Content-Type'
Value (String (Unlimited)) – set the Value to 'application/pdf'
System.HttpHeaders (System.HttpMessage) - set the Value to $httpResponse

Testing the Service

Test the service to ensure that it works!

Run your app and upload a PNG file. You can upload the files on the overview pages you created in the previous step, so make sure you have a link to the file overview page on your home page.
Back in Studio Pro, open the service document, and click the link to the service to display the OpenAPI document (for example, http://localhost:8080/rest-doc/rest/cmsapi/v1).
Try it out by clicking Get/myfile/{myfileid} > Try it out > Execute. The contents will display the binary. You can also test the call in Visual Studio Code using the REST Client extension by making the following call:
```
GET http://localhost:8080/rest/cmsapi/v1/myfile/1
Accept: image/png`
```
Click Get/myfile/{myfileid} to return the content, and you should see the PNG displayed. If you only see the binary, make sure that you have set the MIME Type.

Retrieve Images or Files from a Published REST Service

You can implement a client in your app that will retrieve binary files from any published REST service, from a Mendix app or anywhere else, and store them in a FileDocument entity.

Right-click on the File Explorer and select Add module, then rename it as CMSClient.
Add an entity to handle the retrieved files.
- In the Domain Model, right click to add an entity called RetrievedFile.
- Double-click on the entity to open the Properties and select the Generalization. To test with the PNG file, we can use System.Image, or System.FileDocument if you want to work with a PDF file.

Then, you can retrieve the image with the Image widget, retrieve a PDF with the HTML/JavaScript snippet widget for PDFs, or retrieve images or PDFs with a microflow.

Retrieve images with the URL of the published REST service by using the Image widget available on the Mendix Marketplace.

To do so, do the following:

Complete the two steps in the Retrieve Files with REST section.
Download the Image widget from the Mendix Marketplace and import it into your app.
In the Toolbox, click Widgets and search for “Image”.
Drag the Image widget onto a page.
Double-click the widget you dragged onto your page to open the Properties.
In the Data source field, select the Image URL for Image type.
Paste the location of the file in the REST service (for example, http://localhost:8080/rest/cmsapi/v1/myfile/1).

Retrieving PDFs Using the HTML/JavaScript Snippet Widget

Retrieve PDFs with the URL of the published REST service by using the HTML/JavaScript Snippet widget available on the Mendix Marketplace.