Helping you drive digital innovation
Subscribe
RSS Feed of the Mendix Blog
Thanks for Subscribing

Keep an eye out for Mendix resources coming straight to your inbox.

Consuming Your First REST Service

on May 2, 2014

Share:

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.

Preparations

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:

{
  "elapsedMilliseconds": 42,
  "count": 43,
  "artObjects": [
    {
      "links": {
        "self": "https://www.rijksmuseum.nl/api/en/collection/SK-A-2227",
        "web": "https://www.rijksmuseum.nl/en/collection/SK-A-2227"
      },
      "id": "en-SK-A-2227",
      "objectNumber": "SK-A-2227",
      "title": "Korensnijder met hoed, van achteren gezien",
      "principalOrFirstMaker": "Vincent van Gogh",
      "webImage": {
        "guid": "b46d6636-cead-450b-9201-3960b226af8a",
        "width": 1921,
        "height": 2500,
        "url": "http://lh5.ggpht.com/LeONPNh8oPUpjMUWxUe3d0G_DkktDb3FKgQuy9rRe-1usn_Ls6u5yrQfvlLC3nARNJWTe3ZOLUR7-hbe1Zai6NN3RU8=s0"
      },
      "productionPlaces": []
    }
}

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.

Capture

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

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

The Rijksmuseum Art Search App

Contribute!

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!

Subscribe to Our Blog

Receive Mendix platform tips, tricks, and other resources straight to your inbox every two weeks.

RSS Feed of the Mendix Blog

About Michel Weststrate

Michel is a 30 years old software developer graduated at the Delft University of Technology and currently working as lead developer at Mendix / Sprintr. Michel is happily married to Elise and father of two daughters. In his rare free time, you can find him reading or writing even more software.

  • Pim van der Noll

    Nice blog Michel and module! Consuming was slightly easy. Have you planned a blogpost for publishing a REST interface as well? (seems harder to get it work)

    keep up the good work!

  • Farai

    thank you very much for your contribution, how do you integrate mendix with a product like intercom

  • Michel Weststrate

    I will!

  • Michel Weststrate

    Hi Farai,

    I am not familiar with intercom, but if they provide a JSON based REST api you should be able to follow the instructions from their documentation once you have imported the REST services module into your Mendix project. Any specific questions about the implementation can best be discussed at https://mxforum.mendix.com.

    Success!

    Michel

  • The full source of the Rijksmuseum demo project can now be downloaded from: https://github.com/mendix/RestServices/tree/master/demos

  • Farai

    Yes Michel, they provide JSON based REST api. Can you please provide more info on how you included instructions from the Rijksmuseum API in your java actions.
    Thanks

  • Adam Fothergill

    Hey Michel, maybe I’m missing something, but how do you obtain the API key? I clicked the link you provided but it just brings me to the Rijksmuseum website. Thanks!

  • Dear Farai,

    That entirely depends on your actual use case. I suggest to post these kind of questions at mxforum.mendix.com, where our whole community can either answer or profit from your question. You can post the relevant parts of the documentation there for example.

    With kind regards,

    Michel

  • Hi Adam,

    This link is probably better: https://www.rijksmuseum.nl/en/rijksstudio

    From there on, press “start your own rijksstudio” to register and receive an api key. If it is just for testing purposes, you could also use the api key that is provided in the demo project at: https://github.com/mendix/RestServices/tree/master/demos

  • hgeldenhuys

    Michel, very nice module. Doesn’t look like it could be improved, tested it and it works nice. Only suggestion I would make is to make this standard in the platform and easy enough so you don’t need a Support Ticket to expose the endpoints in the Mendix cloud. Very well done and thanks! Its long overdue 😉