Chapter 7: Calling a Web API from Node-RED

In this chapter, let's call a web API from Node-RED. Basically, in Node-RED, processing is performed as per the created flow, but it is JSON data that connects processing. In that sense, it is very compatible with web APIs.

Let's get started with the following four topics:

• Learning about the RESTful API
• Learning about the input/output parameters of a node
• How to call the web API on a node
• How to use the IBM Watson API

By the end of this chapter, you will have mastered how to call any type of web API from Node-RED.

Technical requirements

To progress through this chapter, you will need the following:

• Node-RED (v1.1.0 or above)

The code used in this chapter can be found in Chapter07 folder at https://github.com/PacktPublishing/-Practical-Node-RED-Programming.

Learning about the RESTful API

Many of you reading this book may already be familiar with web APIs. However, let's review the RESTful API in order to call a web API with Node-RED.

REST stands for Representational State Transfer. RESTful API basically refers to the invocation interface in HTTP of a web system that is implemented according to "REST principles." So, in a broad sense, it's safe to say that the REST API and RESTful API are the same things. So, what exactly is the RESTful API? We will learn the outline and principles of the RESTful API, and the advantages and disadvantages of using the RESTful API, in this section.

REST was proposed by Roy Fielding, one of the HTTP protocol creators, around the year 2000, and is a set (or way of thinking) of design principles suitable for linking multiple software when building a distributed application. In addition, the RESTful API is an API designed according to the following four REST principles:

• Addressability: It has the property of being able to directly point to a resource through a URI. All information should be represented by a unique URI so that you can see at a glance the API version, whether to acquire data, update, and so on.
• Statelessness: All HTTP requests must be completely separated. State management such as sessions should not be performed.
• Connectivity: This refers to the ability to include a "link to other information" in one piece of information. By including a link, you can "connect to other information."
• Unified interface: Use HTTP methods for all operations such as information acquisition, creation, update, and deletion. The HTTP methods, in this case, are acquisition ("GET"), creation ("POST"), update ("PUT"), and deletion ("DELETE").

These are the four principles. As you can see from these four principles, a major feature of REST is that it makes more effective use of HTTP technology and has a high affinity with web technology. Therefore, it is currently used for developing various web services and web applications.

With the recent widespread use of smartphones, it is becoming more obvious that business systems can be used not only on PCs but also on mobiles. In addition, not just one system but a system that can be linked with multiple systems and various web services will not be selected by users. RESTful APIs are receiving a great deal of attention as an indispensable tool for solving these problems.

As the following figure shows, a web API can be called from anywhere via the internet:

Figure 7.1 – RESTful API diagram

Now, let's recall what Node-RED is. Its workflow tool-like style is like a standalone tool, but Node-RED is certainly one of web applications too. In other words, it's an application that works very well with the RESTful API described here.

Next, let's cover again what kinds of parameters Node-RED nodes have.

Learning about the input/output parameters of a node

Of the many nodes that Node-RED has, not many are suitable for calling web APIs (REST APIs). A typical node used when calling the web API is the http request node.

To call an external API on Node-RED, simply set the endpoint URL of the API to the URL property of the http request node.

For example, when it is necessary to set a parameter in the endpoint URL when calling an API, it is possible to set the output value of the previous node connected. The method is very easy. Instead of a literal string, you can just set the {{payload}} variable in the value setting part of the parameter.

In {{payload}}, the character string inherited from the previous processing node is entered.

Take the following example (note that this URL does not exist): http://api-test.packt.com/foo?username={{payload}}&format=json:

Figure 7.2 – Setting the API endpoint URL with {{payload}} as a parameter

The process of the http request node cannot be executed by the http request node alone. Before the http request node, it is necessary to connect the trigger process, such as the inject node. At that time, if there is a parameter you want to pass to the API call, that is, the http request node, please set it in msg.payload.

If the API you want to call in the http request node is POST, the JSON data to be included in the request will be satisfied as a request parameter by creating it in the preprocessing node, storing it in msg.payload as it is, and connecting it to the http request node.

By using the http request node like this, API cooperation can be easily realized. API calls are important for linking multiple services on Node-RED. For example, the function node of Node-RED is basically processed by JavaScript, but by making a program developed in other development languages, such as Java, into an API, it can be used by calling from Node-RED.

How to call the web API on a node

So far, we've learned what a RESTful API is and which node is appropriate for an API call.

In this part, let's create a flow that actually calls the API from Node-RED and learn how to call the API and how to handle the result value from the API.

There are a few things to think about first, such as which API to call. Fortunately, various APIs are published on the internet.

This time, I would like to use the OpenWeatherMap API. In OpenWeatherMap, for example, the following APIs for data acquisition are prepared:

• Current weather data
• Hourly forecast 4 days
• Daily forecast 16 days
• Climatic forecast 30 days
• Weather alerts
• And more...

For more information, please see the official website of OpenWeatherMap: https://openweathermap.org/.

Okay, let's prepare to use the OpenWeatherMap API.

Creating an account

To use the OpenWeatherMap API, we need to create an account. Please access the following URL: https://openweathermap.org/.

If you already have an account, please log in without taking the following steps.

For those who are using it for the first time, please click the Sign In button, and then click the Create an Account link. It is easy to register. Just follow the guidance and confirm the email sent to you by OpenWeatherMap after registration. This is what the creating an account page looks like:

Figure 7.3 – Creating an OpenWeatherMap account

Next, let's create an API key.

Creating an API key

When you log in to OpenWeatherMap, you can see the API keys tab, so please click it. You already have a default API key but please create a specific API key for this tutorial. Enter any key string and click the Generate button.

Please note that the API keys shown in this book are created by me as a sample and cannot be used. Be sure to create a new API key in your account:

Figure 7.4 – Generating API key

Important note

After creating the API key, the key will not be activated for 10 minutes to a couple of hours. If a web response error such as 401 is returned even when you access the API endpoint URL described in the next section, the specified API key may not have been activated, so please wait and try again.

Checking the API endpoint URL

To check your API endpoint URL, follow these steps:

1. Click the API button on the menu bar. You can see some APIs there.
2. In this tutorial, we will use Current Weather Data, so please click the API doc button under Current Weather Data:
   

   Figure 7.5 – Opening API doc of Current Weather Data

3. This API has some types of parameters such as By city, By city ID, By zip code, and so on. Please select By city name with the parameter city name and API key.

   API doc, city name, state code, and country code are from ISO 3166. The URLs under the API call area are endpoint URLs for using this API. Please copy this URL to the clipboard:

Figure 7.6 – API endpoint URL with parameters

Next, let's see whether we can run this API or not.

Checking that the API can run

Let's try to use this API. You just have to open your browser, paste the URL, and replace the city name and API key with yours. You can choose any city name, but the API key is the specific one you created in the previous section:

Figure 7.7 – Calling the API and getting the result

I have now confirmed that this API works correctly. Now let's call this API from Node-RED and use it.

Creating the flow calling the API

Now let's create a flow that calls the OpenWeatherMap API on Node-RED. Start Node-RED in your environment. You can use either standalone Node-RED or Node-RED on IBM Cloud:

Figure 7.8 – The flow to use the API

For this, the flow is very simple and easy to make. Please follow these steps to make the flow:

1. Place one inject node and two debug nodes on the palette. These nodes can be used as default. No change in the settings is required here.
2. Place the http request node on the palette, then open the settings panel of the http request node and set the API endpoint URL with your parameters (city name and API key) in the URL textbox of the settings panel, as shown in the following figure:
   

   Figure 7.9 – Setting the API endpoint URL with your parameters

3. Place a json node on the palette. This node can be used with the defaults. No changes in the settings are required here. But, just in case, let's make sure that the Action property of the json node is set to Convert between JSON String & Object. This is an option that will convert the JSON data passed as the input parameter into a JavaScript object:
   

   Figure 7.10 – Checking the Action property

4. Wire all nodes as shown in the following figure:
   

   Figure 7.11 – Wiring all nodes

   Please wire the timestamp node and the http request node. The http request node output is wired to the json node and the debug node. Lastly, please wire the json node output to another debug node.

5. After changing the settings and wiring all the nodes, you need to deploy and click the switch of the inject node. You can now see the data on the debug window in the right-side panel:

Figure 7.12 – Result data (JSON) on the debug window

You can also see the result data as a JSON object on the same debug window as in the following screenshot:

Figure 7.13 – Result data (object) on the debug window

Congratulations! You have succeeded in making a sample flow by calling the OpenWeatherMap API. If you didn't succeed in making this flow completely, you can also download this flow definition file here: https://github.com/PacktPublishing/-Practical-Node-RED-Programming/blob/master/Chapter07/open-weather-flows.json.

In the next section, we will learn about the convenience of using the IBM Watson API with Node-RED on IBM Cloud.

How to use the IBM Watson API

In the previous section, you learned how to call the API and handle the resulting values from the API.

In this section too, we will create a flow that actually calls the API from Node-RED, but we will learn how to call the Watson API provided by IBM. We will also create a flow that actually calls the API from Node-RED, but we will learn how to call the Watson API provided by IBM.

Why Watson? Watson is a brand of artificial intelligence services and APIs provided by IBM.

All Watson APIs can be used from IBM Cloud. So, by running Node-RED on IBM Cloud, you can effectively use Watson's services. This has advantages such as when calling the Watson API from Node-RED, implementation of authentication can be omitted.

Watson can be called from environments other than IBM Cloud, so it can be called directly from a Raspberry Pi or can be used from either cloud platforms such as AWS and Azure or on-premises environments. See the following figure, showing what a Watson API looks like:

Figure 7.14 – Watson API diagram

For more information, see the IBM Watson official website: https://www.ibm.com/watson.

Okay, let's see how easy it is to use the Watson API on Node-RED on IBM Cloud.

Logging in to IBM Cloud

If you've followed the steps from the first chapter, you should already have an IBM Cloud account. Just log in to IBM Cloud (https://cloud.ibm.com).

If you do not have an IBM Cloud account, create one from the following URL and log in to IBM Cloud. See Chapter 6, Implementing Node-RED in the Cloud, for detailed instructions: http://ibm.biz/packt-nodered.

Starting Node-RED on IBM Cloud

In the previous section, we created a sample flow using standalone Node-RED or Node-RED on IBM Cloud. Of course, you can use the standalone version of Node-RED to call the Watson API, but some benefits will be lost. So, we will work with Node-RED on IBM Cloud in this part.

As in the previous step, if you have not used Node-RED on IBM Cloud yet, please return to Chapter 6, Implementing Node-RED in the Cloud, and run through it to activate Node-RED on IBM Cloud before moving on to the next step.

Creating the Watson API

Next, create Watson's service on IBM Cloud. Strictly speaking, this means creating an instance as a service so that you can call the Watson API service provided on IBM Cloud as your own API.

Watson has several APIs, such as voice recognition, image recognition, natural language analysis, sentiment analysis, and so on. This time, I would like to use the sentiment analysis API.

Follow these steps to create a Watson Tone Analyzer API service:

1. Search for Watson from the catalog. On the dashboard, please click the Catalog menu item and search for tone analyzer, and then select the Tone Analyzer panel:
   

   Figure 7.15 – Searching Watson services

2. Please refer to the following list and Figure 7.16 to fill in each property:

   a. Region: Dallas (you can select any region, but Dallas is recommended)

   b. Pricing plan: Lite (free pricing)

   c. Service name: Default (you can modify this to any name you want to use)

   d. Resource group: Default (you can't select anything else for a Lite account)

   e. Tags: N/A

3. After entering/selecting all the properties, click the Create button:
   

   Figure 7.16 – Creating a Tone Analyzer service

4. You can see the status as Active on the Tone Analyzer instance dashboard when it is created and activated. Please check the API key and URL. API keys and URLs are used when the API is called from any application. However, these are not used in this tutorial because Node-RED on IBM Cloud can call the Watson API without authentication coding.

   You can check the API key and URL from the Manage menu on this screen:

Figure 7.17 – Checking your credentials

In the next section, we will connect Node-RED and the Tone Analyzer service.

Connecting Node-RED and the Tone Analyzer service

As you already know, Node-RED can call the Watson API without coding for authentication. We need to connect Node-RED and the Watson API instance before using Node-RED with the Watson API. In the last step, we created the Tone Analyzer API instance, so let's connect these two instances as follows:

1. Click the IBM Cloud logo button at the top left to move to the main dashboard.
2. Click the View all button on the Resource summary panel.
3. Click the Node-RED instance (application) name in the Cloud Foundry apps area:
   

   Figure 7.18 – Selecting the Node-RED service you created

4. Click the Connections menu and then the Create connection button:
   

   Figure 7.19 – Creating a connection for Node-RED and Watson

5. Check the Tone Analyzer service and click the Next button:
   

   Figure 7.20 – Clicking the Next button to select the connecting service

6. No modification is needed for the access role and service ID. Click the Connect button:
   

   Figure 7.21 – Clicking the Connect button to complete the connection

7. We need to restage Node-RED to activate the connection. Click the Restage button:
   

   Figure 7.22 – Clicking the Restage button to start restaging the Node-RED service

8. Please wait until the restaging of your Node-RED instance is completed. Once completed, you will get a successful connection with the Running status. After that, please open the Node-RED flow editor via the Visit App URL link:

Figure 7.23 – Checking the status of the Node.js runtime for the Node-RED service

You have succeeded in preparing the Node-RED and Watson API flow. Next, let's create the flow by calling the Tone Analyzer API.

Creating the flow by calling the Tone Analyzer API

Now, let's create a flow that calls the Watson Tone Analyzer API on Node-RED. You already started Node-RED on IBM Cloud. Either standalone Node-RED or Node-RED on IBM Cloud can be used.

To proceed with this tutorial, you need to install the following two nodes:

• node-red-node-twitter: This is a node that acquires and posts tweets to Twitter:

Figure 7.24 – Installing node-red-node-twitter

• node-red-node-sentiment: This is a node that adds a sentiment object in the passed msg.payload. It is used when passing parameters to the Watson Tone Analyzer API:

Figure 7.25 – Installing node-red-node-sentiment

Search for these nodes in the palette and install them to your Node-RED flow editor. After that, make a flow as shown in the following figure:

Figure 7.26 – The flow to use the Tone Analyzer API

In this flow, the function node processes the text, tone, and sentiment included in the result value obtained from Twitter so that they are output as separate debugs. This is to make the results easier to see.

This flow is a little more complicated than the flow you created in the previous step. Please follow these steps to make the flow:

1. Make a Twitter ID (Twitter account) and create an application on your Twitter Developer account to authenticate for accessing tweets via your Twitter account.
2. Access Overview under Projects & Apps on Twitter Developer, and then click the Create an app button:
   

   Figure 7.27 – Creating an app on Twitter Developer

3. Set the App name with any strings, and click the Complete button.
   

   Figure 7.28 – Setting a name of your app

4. After that, please check the Access token & access token secret area.

   You will see the tokens. Please note and save your access token and access token secret. These will be used for the setting of the twitter in node too:

   

   Figure 7.29 – Note your token and token secret

5. Place the twitter in node on your workspace, and double-click it to open the settings window:
   

   Figure 7.30 – Placing the twitter in node

6. Click the edit (pencil icon) button on the settings window to edit your Twitter information:
   

   Figure 7.31 – Editing the Twitter properties

7. Set your Twitter ID, API key, and token.

   The values for API key, API key secret, Access token, and Access token secret should be taken from your text editor from step 8.

8. After setting these settings, please click the Add button to return to the main settings window of the twitter in node:
   

   Figure 7.32 – Configuring your Twitter information

9. Select all public tweets for Search, and set for to #nodered as the hashtag. You can set any name for Name.
10. Finally, click the Done button to finish adding these settings and close the window:
    

    Figure 7.33 – Finalizing the settings of the twitter in node

11. Place the sentiment node on your workspace. It will be wired after the twitter in node.

    For this node, no properties are needed to be set or changed:

    

    Figure 7.34 – Placing the sentiment node

12. Place the tone analyzer v3 node after the sentiment node sequentially on your workspace:
    

    Figure 7.35 – Placing the tone analyzer v3 node

13. Open the settings panel of the tone analyzer v3 node and set the Method and URL properties as follows:

    a. Name: Any string you want to name

    b. Method: General Tone

    c. version_date: Multiple Tones

    d. Tones: All

    e. Sentences: True

    f. Content type: Text:

    

    Figure 7.36 – Configuring the tone analyzer v3 node properties

14. Place the function node after the tone analyzer v3 node sequentially on your workspace:
    

    Figure 7.37 – Placing the function node

15. Open the settings panel of the function node and code JavaScript with the following source code:

    msg.payload = {

        "text" : msg.payload,

        "tone" : msg.response,

        "sentiment" : msg.sentiment

    };

    return msg;

    Please refer to the following screenshot for the coding for the function node:

    

    Figure 7.38 – JavaScript source code for the function node

    You can get the code here: https://github.com/PacktPublishing/-Practical-Node-RED-Programming/blob/master/Chapter07/format-payload.js.

16. Finally, put three debug nodes in parallel after this function node. Each debug node's settings are as follows:
    • msg.payload.text: For the debug tab
    • msg.payload.tone: For the debug tab
    • msg.payload.sentiment: For the debug tab

      See Figure 7.26 for the wiring instructions. We have finished making configurations for the nodes of the flow.

Testing the flow

The flow is now complete. When you click the deploy button and the twitter in node connects to Twitter using your account, it will automatically retrieve the tweets that meet your criteria and process the subsequent flow.

This is done automatically, so you don't have to take any special action.

Here, it is set to get all tweets that have #nodered as a hashtag. If you don't get many tweets, it means that a tweet that contains the specified hashtag has not been created, so please change the hashtag set in the twitter in node and try again.

All the processing results of this flow will be displayed in the debug tab.

It is msg.payload.text that extracts the tweet body from the acquired tweets and displays it:

Figure 7.39 – Result of getting the tweet body

It is msg.payload.tone that extracts and displays emotions detected in the acquired tweets:

Figure 7.40 – Result of tone analysis from the tweet

It is msg.payload.sentiment that judges whether the sentiment is positive or negative in the acquired tweets:

Figure 7.41 – Result of the sentiment of a tweet

Congratulations! You have succeeded in making a sample flow by calling the Watson API. If you didn't succeed in making this flow completely, you can also download this flow definition file here: https://github.com/PacktPublishing/-Practical-Node-RED-Programming/blob/master/Chapter07/get-sentiment-twitter-flows.json.

Summary

In this chapter, we learned how to create a sample flow (application) that calls two types of web APIs. We are gradually getting used to creating complicated flows. Use cases for calling web APIs are frequently found in Node-RED. The flow creation methods we learned about here will help us to create more complex flows in the future.

In the next chapter, let's learn about a project feature that can be integrated with repositories such as GitHub, which is a function added from Node-RED version 1.0.