HTTP/HTTPS Integration
Last updated
Last updated
HTTP (Hypertext Transfer Protocol) is one of several types of protocols used for communication between systems, and its operation is by the use of hypertexts, which are nothing more than a structured text that uses logical links (hyperlinks) between nodes containing text.
Its operation follows the request-response model through a client-server, so it is important that each request made has its response, even if this is an empty data set.
To illustrate an HTTP communication, we have a client that sends an HTTP request message, for example, the request to an API, and the server, when verifying this request, responds to the client with the desired data. If, for some reason, the server does not have this data, or the API is not working properly, there is the return of a response to the client with an error, or the information of non-existence of the data.
The HTTP protocol is also a stateless protocol, that is, the server does not need to store session information, and each request is completely independent of the other.
In this protocol, there is a request and response structure, which can be exemplified as:
Request:
A command or request, + optional headers + optional body content.
Answer:
A status code + optional headers + optional body content.
Logic Builder is already configured with the main nodes for communication using HTTP, having the nodes HTTP IN, HTTP Response and HTTP Request.
To find these nodes, go to Logic Builder, Figure 1, and in the node palette, type HTTP, Figure 2.
There will be three HTTP nodes, and the function of each one will be addressed throughout this article.
HTTP IN: This node is the web server, that is, it is the input to serve the data to a request made. To do this, it needs to be configured correctly to accept a request. This node supports the get, POST, PUT, DELETE, and PATCH methods as shown in figure 3:
The GET method is widely used in HTTP. Below is a list with descriptions of the types that the HTTP IN node contains.
GET: is a method that requests a specific resource on the server. When there is a requirement that uses the get method, it should return only data.
POST: is a method used to send data to a server. Frequently causing some change in the state of the requested resource.
PUT: This method is used to replace or create a new resource or representation of a resource in the target with new data.
DELETE: As its name suggests, this method removes a specific resource.
PATCH: is a method used to apply, when necessary, partial modifications to a hosted resource.
In order to illustrate the operation of the HTTP IN node on the platform, a simple server will be configured to serve as an API example for a resource that can be used later.
Using the HTTP IN node, select the get type, notice in figure 4 that in the URL the request "HTTP tutorial" will be used and this name can be changed according to the application.
To test the configuration, simply create a simple flow with a debug, as shown in figure 5, and use a browser to request the service.
To test the request via web, it will be necessary to use the following url structure: https://url_application/ applications/logic Builder/HTTP tutorial, when accessing this url in a browser of your choice, it is possible to see that in the platform there was a request message, but in the browser there was an error, '504 Gateway Time-out', this error happens because the server did not respond to the request, so we entered the second HTTP node, HTTP Response.
As stated earlier, every HTTP request needs a response, otherwise there will be an error return, as occurred in this example. In order for this not to occur, it is necessary to use the HTTP Response node. Place the node connected directly to HTTP IN, as shown in Figure 6 and request it by the browser again, note that on the browser request page it will no longer return an error, but an empty object, since no data was inserted into the set of this flow.
To exemplify the sending of information we will create a simple object, containing three values, "Name", "Information" and "Status", written as follows: {"Name":"HTTP Tutorial", "Information":23.78, "Status":"Active"}
To enter this information use a "Function" node and write the message as shown in figure 7.
In order for the flow to work in the correct way, place the "Function" node as shown in figure 8.
Note that when you update the browser, the information that was written in the msg.payload object will appear.
Now on the platform it is possible to see in the "Debug" node a set of information, the main information is: the payload and the objects "req" and "res", these objects are the minimum necessary to create an HTTP flow, and the latter, "req" and "res", must necessarily be in the response of the request. Since these objects have the verification values that indicate the request of the service and its response. Without these objects in the request response, the flow will not work and will present errors.
The use of HTTP brings many possibilities of integration in the loT environment, since it is possible to create APIs to be used in several applications. For this to become automated, it is necessary that, constantly, some device or service sends information to nurture this API, and for this to be done, the HTTP Request node is used.
The HTTP Request node is mainly used to make HTTP requests on a server, when these requests are made it is possible, in addition to verifying the data, to create a logic capable of changing or entering new information, thus creating an automated structure.
The operation of this node consists of sending a request, returning a response on its output. Therefore, this node reads with a request and response.
Unlike the other two HTTP IN and HTTP Response nodes, HTTP Request will have some more in-depth settings that will be explained below.
As shown in figure 9, the HTTP Request node presents the main methods of the HTTP protocol, which are, get, POST, PUT, DELETE and HEAD, the latter requesting an identical response to a get request. But without the body of the answer. Very useful for retrieving meta-information written in response headers, without having to carry all the content.
In addition to the methods, the HTTP Request node has other settings that can be used according to the application. Each of them will be described below:
Method: method with which one wishes to work.
The URL of the resource: This setting is used to enter the address of the web page or services for requesting the information.
Payload: is sent as request body.
SSL: Enables settings for secure connection.
Authentication: If the site or service requires authentication, a basic authentication can be done in this box.
Active Connection: Used to keep the connection active at all times.
Proxy: enables the use of a proxy in the connection.
Answer: the type of response expected by the server, which can be:
UTF-8 String
Binary Buffer
JSON Object
An example widely used in applications made in the thingable! and using an HTTP Request is the ‘GET Devices’ API. For more information on the APIs, access the link.
This API will return all devices registered in your environment, to exemplify the use of HTTP Request, let's use this API. To do this, configure the node according to figure 10, in the URL use the link: http://url_aplicacao/api/device-client/devices. Change "your_application" to the name of your application, by inserting this url, in a web browser of your choice, you will receive as a response all devices registered in your environment.
To see the data in Logic Builder it is necessary to create a simple flow, as shown in figure 11. Note that the "Debug" response will be a set of objects with the information of the devices and which will be treated according to the need of the application.
The flow shown in figure 11 can be used to request the information from registered devices, and later make use of this information in the flow under development.
When we want to receive data on the platform over HTTP/HTTPS we have two distinct ways to do this, either by consulting an external data provider API through the request node shown in figure 11, or with the platform working as an HTTP server as shown in figure 8. In the latter, remote device settings can send data to your application's url. If you choose to configure an HTTP server, devices must send the data respecting the chosen HTTP method. For receiving data we can configure the server method as get, PUT or POST, we recommend using the POST method that allows sending a larger amount of data.
To publish data from HTTP/HTTPS services to the thingable SCADA system! it is important that this information is in JSON format.
The HTTP Request node already has an output that transforms the received information into JSON objects, to keep this option active, as shown in figure 13, keep the response as "a parsed JSON object".
With this configuration, the message return will be a JSON object, much easier to handle in Logic Builder. To publish the data to SCADA, use the "ibm iot out" node as shown in figure 13.
The figure below shows the necessary settings to be made in the "ibm iot out" node:
Authentication: Form of authentication to be used. For our application choose "API Key".
API Key: API Key registration to be used. For more details on this key see section obs1 at the end of the document.
Output Type: displays the following options, "device command" and "device event". In this case, "device event" is used to publish the data.
Device Type: msg.deviceType to receive the device type parameter
Device Id: msg.deviceID to receive the device id parameter from the device or you can write directly to the serialNumber that will receive this message.
Format: json. Format of the message that is received by the node.
QoS: Quality of Service. It is parameterized with the receipt of the MQTT message. By default it is kept at 0.
To verify that the data is arriving on the device correctly, simply check in the "Device Manager" tool, in the options column, in the "Device Events" network icon. It will be possible to see the receipt of data in "event" of what was parameterized to send in msg.payload.
It is important to emphasize that for the SCADA to be able to correctly identify the information sent in "msg.payload" it is necessary that the json structure correctly obeys the key structure and type in the values defined in the schema of the device identified in "Device Type" and "Device Id".
For more details on how to configure the schema of a device access our documentation dedicated to the theme Metadata and Schema
After these settings, the data can already be published in SCADA, and later used in the created applications.
Note 1: By default, no thingable! the "ibmiot out" node is already configured with the Key API corresponding to the environment you are working on. If you are unsure whether the credential is valid, click on the credential edit menu to check the details, or create a new one in the Add new ibmiot option. If it is necessary to create a new credential configuration be aware that Logic Builder is an application, so you need application credentials (which are different from device credentials, available when we create a new one), these credentials can be obtained from the IBM Watson Credentials tab within the Service Configurator:
Note 2: If any of the fields in "IBM Watson Credentials" are empty, consult the thingable! support.
Authors: Matheus Widmer
Angelo Guimarães
