Consume REST Services With Native Microflow Actions

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.

REST and the Internet

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:

  • State. This is a resource on a server, stored in some internal format. For example: product data in database.
  • Representation. Not all the data on the server is relevant. Often it needs to be filtered and submitted in a general format that the client can understand. A Representation of the data is sent over the internet. Several common representations are XML, JSON, HTML, or binary data such as an image or PDF file.
  • URL. Unique address to a resource.
  • Method. A textual verb in a HTTP request to indicate what you want to do with the resource. For example: GET a resource, POST a new resource, PUT an updated resource, PATCH a resource to make small changes or DELETE a resource. This verb is stated literally in the HTTP message.
  • Headers. HTTP headers give extra information to a message. For example, Content-Type: application/json specifies that the representation of the message is in JSON format.
  • Status code. A simple number added to an HTTP response message. For example: 200 means OK, 404 means Resource not found.

Example: Pet Store

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.

  • GET http://petstore.swagger.io/v2/pet/100 returns a pet.
  • POST http://petstore.swagger.io/v2/pet adds a new pet to the store.
  • DELETE http://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:

Microflow

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:

rest-call-headers

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).

JSON Snippets and Schema Extraction

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 application/json).

{"id":100,"category":{"id":0,"name":"test"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":"available"}

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:

JsonStructure

Mappings

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.

Select-elements

  • You can easily select which elements from the schema you want to use in your application. You do not have to pollute your domain model with data structure you don’t want to use.

ImportMapping

  • You can drag-and-drop entities onto the mapping and they will automatically be coupled to the incoming data.
  • If you want to customize how the incoming data is being translated into Mendix objects you can do so by coupling a microflow to the mapping. You can opt to update existing objects; you just have to select an attribute that should be used to find the object (key).
  • You can generate entities and associations for the JSON by clicking a button Map automatically. You do not have to create them manually. But of course you are free to make changes or leverage your existing data model. For example, you can make entities Persistable in the Domain Model so the objects can be directly read from the database into a Data Grid on a Page.

By practicing with mappings you will appreciate the ease with which you can handle complex data structures with a few mouse clicks.

Use Mappings in Your REST Call Directly

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.
rest-call-response
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 FileDocument or Image object. Support for binary representations will be added in a later version of Mendix.

Sending Pets to the Pet Store

In our mapping example, we focused on how to GET a pet and map to entities. Other HTTP methods are also supported: for example, POST and 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:

{"id":100,"category":{"id":0,"name":"string"},"name":"doggie","photoUrls":["string"],"tags":[{"id":0,"name":"string"}],"status":available"}


rest-call-request

Conclusion

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!