Product

Consuming a JSON webservice - Part 1 of 2

This is part one of a two part series where we show how to consume a JSON webservice from within your WEM project. At the end of the second part we will have built a simple application that uses the Open Movie Database API to search for a movie and show the details. You can already see the final application working at https://omdb.live.wem.io.

Part two will focus on JSON messages and how to handle them in WEM. This part explores a new feature in WEM that allows you to perform any HTTP web request.

Introducing a new flowchart node

HTTP (Hypertext Transfer Protocol) is the protocol that is used to communicate with web servers. Your browser sends an HTTP request to a web server any time you request a new web page, while webservers use HTTP to communicate with each other through webservices.

We recently added a new node type to the flowchart editor that can perform any HTTP web request, and conveniently called it the "web request node". When you drag this node in your flowchart, you can specify all the aspects that make up an HTTP request message:

  • The url (this includes the scheme, which is either http or https).
  • The request method (GET and POST are the most common methods, but WEM supports all common methods).
  • Request headers - The header fields Accept, Connection and Content-Type are predefined. You can specify any number of additional headers.
  • Query fields - You can manually put the queryfields in the url yourself, but I recommend to specify them separately. This way WEM will take care of proper url encoding.
  • The request body, if applicable. This can either be plain text (for instance, json or xml) or a document such as an image or a pdf file.

When it comes to security, WEM supports basic authentication and client certificates out of the box. Other authentication schemes are often possible through custom HTTP headers.

The web request node also lets you specify how to handle the web response that you get back from the server. You can map each response header to a data field, and the response body can be stored in either a text field or a file field. The node has an error exit that is followed when the server is not available or when the server responds with a 50x Server Error. You can also add exits to handle specific server responses, such as 404 Not Found or 401 Unauthorized.

Using the Open Movie Database API

Searching the Open Movie Database is very easy. It consists of a simple GET request to https://www.omdbapi.com/ with some query fields:

  • s - The movie title to search for.
  • y - The year of release (optional).
  • r - The message format of the response (json or xml).

There are more optional query fields, but these are the three that are used in the demo application. You can even try the API in your browser, and inspect the JSON response:

http://www.omdbapi.com?s=Matrix&y=1999&r=json

For our example I created a simple flowchart:

Flowchart

The first node contains a simple form where the user can enter (a part of) the title and year of the movie. I created two data fields named [Search.Title] and [Search.Year] for this form.

searchfields

The second node is the new web request node. It performs a GET request to the url "http://www.omdbapi.com/". No authentication is needed. The response body is stored in an other data field [Response.Json]. This is a plain text field. The following three query fields are added for this request:

queryfields

Note that the query field r contains the literal text "json". This instructs this particular webservice to send the response in json format.

The last node in the flowchart is an overlay that shows the JSON message. When I searched for "The Godfather", I received the following json response:

response

That's it for part one. In part two we will import this json message into a data list so that we can handle the response in a meaningful way.