Consuming Your First REST Service
JSON and REST are hot. And rightfully so. Many public (social) websites like Dropbox, Github, Google, Facebook, etc. offer JSON-based RESTful APIs as their only or preferred way for integration during enterprise application development. The JSON and REST ‘standards’ are easy to read and their simplicity and flexibility are preferred by many developers over the more strict yet more complex WSDL / SOAP standards. With the REST services module, the full power of JSON-based REST APIs is available to Mendix developers.
This particular mobile app design module serves three goals: consuming services, publishing services and synchronizing data between (Mendix) apps by combining consume and publish. In this post, we will consume our first JSON-based REST services by integrating with the API of the world famous Rijksmuseum which allows us to search for art.
Let’s start by creating a new AppCloud app in a Mendix 5.3.1 modeler (or higher). This allows for deployment in a sandbox later on. Once the project is created, download the latest versions of the REST Services and the Community Commons modules into your project. We are now ready to start building the integration.
From the Rijksmuseum API, we will be consuming the following endpoint: https://www.rijksmuseum.nl/api/en/collection/?key=<api key>&format=json&q=<search query>
After you have obtained an API key, you can simply test this service in your browser by filling in both fields in the URL stated above (you can use Van Gogh as example search query). This should result in something similar to the following JSON fragment:
"title": "Korensnijder met hoed, van achteren gezien",
"principalOrFirstMaker": "Vincent van Gogh",
Consume from Mendix
Now let’s define a data model to consume this service. We create a Query entity to store the search request, and a Results object to store the result. Then we add all interesting pieces of the result JSON to our domain model, in such a way that it reflects the structure of the JSON response, according to the JSON deserialization rules described here. This results in the domain model listed below. Note that we linked the Query and Results object to each other to be able to display it in the interface.
Next we create a page that allows users to enter the search query, show the results in a datagrid over the provided association, and add a button that will execute the search for us. We use an image viewer widget from the App Store to show the image URL that has been returned by the service.
The Search Form
Now that we have all the pieces in place, we are ready to consume the service in the Search microflow. The actual implementation is pretty straight forward. First, we build up the request URL. Second, we prepare the Results object in which the data should be stored. We are now ready to perform the actual request by invoking the request operation, and providing it our URL, Query object and Results object. Finally, we attach the results to the original Query object and refresh the Query object so that the results can be shown in the client.
That’s all folks! We are now ready to run the app, so we hit the ‘deploy to sandbox’ button in the Modeler and we are ready to use the app.
The Rijksmuseum Art Search App
We just the scratched the surface of what the REST Services module can do for you, so make sure to check out the full documentation; the module is able to invoke most, if not any, REST service which is based on JSON, form-data, multipart or binary data. Publishing a REST API for your microflows or data model is pretty straightforward too.
This module is completely open source so feel free to report issues, or even better, submit patches at the GitHub repository. We are eager to see your contributions!