Pieter van Balen on June 29, 2016
Mendix 6.6 contains a major new feature that will help you with calling REST services and handling data. It was originally scheduled for Mendix 7, but since our community is so enthusiastic about this feature, we decided to release it now!
With our new release you can call REST services with a new microflow action. Since REST responses are often in JSON format, we have extended our data mapping documents to handle JSON as well as XML.
The idea behind REpresentational State Transfer (REST) is very close to the initial architecture of the internet: The HyperText Transfer Protocol (HTTP). HTTP was designed to transfer content from a server to a client and vice versa. In the early days, the content was often textual and in the form of HTML (HyperText Markup Language). The content was stored on a server and was uniquely identified by an address: a URL (Universal Resource Locator). For example, by typing the URL in a browser you could get a webpage. Or you can post data to a URL when you upload a file to a server.
If you generalize this initial idea, you can understand the meaning of REST. There are 6 essential elements:
POSTa new resource,
PUTan updated resource,
PATCHa resource to make small changes or
DELETEa resource. This verb is stated literally in the HTTP message.
Content-Type: application/jsonspecifies that the representation of the message is in JSON format.
Resource not found.
A simple example to start using REST is Swagger’s Petstore. This is a public REST example where anybody on the internet can submit their pet descriptions and see the pets of others.
GEThttp://petstore.swagger.io/v2/pet/100 returns a pet.
POSThttp://petstore.swagger.io/v2/pet adds a new pet to the store.
DELETEhttp://petstore.swagger.io/v2/pet/101 deletes a pet.
In the Mendix Modeler, you can add a Call REST action to a microflow. You can specify the location (URL), the HTTP method and HTTP headers. See the image below:
By making a GET request to the above URL, we get a representation of a pet with ID 100 back in JSON format. In a HTTP header we specify that we accept JSON in the response:
Note that anybody can POST their pets to swagger, so if somebody else PUT a monster into the pet, you may want to try another number. If somebody DELETED the pet, you can quickly restore the pet by going to http://petstore.swagger.io/#!/pet/addPet, click on the example value and then click ‘Try it out!’; this will add a default pet with ID 100. Or of course you can POST a pet yourself with the Call Rest action (see the last section of this blog).
The JSON format is a Representation of a pet in a language that a machine can understand. We have made it easy to transform the JSON reply into Mendix objects, for example to display the information on a Mendix generated page. REST services often come with documentation that shows how data is sent back to you. The Pet Store documentation comes with an example JSON snippet (see http://petstore.swagger.io/#!/pet/getPetById with response content type
If you paste this snippet into a Mendix ‘JSON Structure’ document (click Format and Refresh), Mendix will extract the structure of the data being sent back:
The extracted structure is used in an Import Mapping document. The mapping basically specifies how incoming JSON data should be translated into Mendix objects. Mappings are a unique tool in Mendix and very powerful to transform JSON or XML into entities that you can use. The pet example is relatively simple, but in other services representations can grow fairly complex. The mapping tool in Mendix allows you to deal with data complexity in a very intuitive way.
By practicing with mappings you will appreciate the ease with which you can handle complex data structures with a few mouse clicks.
You can easily couple a data mapping to your REST call. Following our pet example: any pet that is received from the service will be mapped to a PET entity. You do not have to write complex expressions to do that, everything is handled by our visual mapper.
Our mapping documents support the XML format as well. If you receive textual data in another format than JSON or XML, you can store the result in a string variable, so you can analyze it later in your microflow. If your REST call responds with binary data, such as an image or PDF file, we will allow you to store it in a
Image object. Support for binary representations will be added in a later version of Mendix.
In our mapping example, we focused on how to
GET a pet and map to entities. Other HTTP methods are also supported: for example,
PUT: they require you to build a message to be sent to the server (the message contains a representation of the pet you would like to send). Our Export Mapping documents also support converting Mendix objects to JSON or XML. They look the same as Import Mappings, but of course the arrows are reversed! And you can reuse all JSON structure documents that you have created in your project, to avoid you having to do repetitive work. For very simple requests, you can also use a string template to build up the HTTP message. Try pasting this JSON snippet into a
POST request to http://petstore.swagger.io/v2/pet:
As an app developer, you can’t avoid integrations with other systems nowadays. We have made integrations to REST services very easy by adding a Call REST microflow action. To handle data sent to and from the REST services, Mendix supports both JSON and XML representations. Mapping documents are very intuitive to handle data structures and are fully integrated into our REST calls.
Try it yourself and find out how integrations can be powerful and fun!
Receive Mendix platform tips, tricks, and other resources straight to your inbox every two weeks.