Welcome to Part three of the API Connector series. In Part One we learned how to add API connectors to our account and in Part Two we learned how to use the API Connectors in a bot to extract weather conditions.
In part three we will be elaborating on some technical details that were not discussed in the previous tutorials. This extra information is going to help all Bot builders even without an IT background comprehend the function of APIs and Variable Mappers better.
To get the weather information we need an API Connector node. API connectors are tools that allow different software systems to communicate with each other by sending and receiving data. They act like bridges, connecting apps and services to share information. This helps automate tasks and integrate features across platforms.
Remember that we selected AccuWeather as the provider with “Weather – Get City ID” as our connector? AccuWeather’s API uses “city IDs” to uniquely identify specific locations. These IDs are unique numbers that AccuWeather assigns to every city or location in their database, which helps avoid confusion between cities with similar names. When you query the AccuWeather API for weather data, you need to provide the city ID instead of the city name. Therefore, at this stage, we are asking the API Connector to find out the ID for our selected city so that in the next stage, we can request the weather forecast for that particular city.
When setting up the API connector, we selected Get as our connector method. You need to know that API connectors allow applications to communicate with each other through a set of protocols and methods. These methods provide the foundation for how APIs manage and manipulate resources on a server. Depending on the use cases, we would have one or more of the methods to choose from.
The methods are:Â
- GETÂ which is used for retrieving data;Â
- POSTÂ which is used to send data to create something new;Â
- PUTÂ which updates or replaces an entire resource;
- DELETEÂ which is used to remove a resource; andÂ
- PATCHÂ which updates part of a resource.
Back to our example of getting weather forecast, as the name suggests, we are trying to retrieve the weather data from AccuWeather. Therefore, our only logical method is Get.
Since you are designing the bot to report on different city weather conditions, in the Configure connector modal your Value shall be set as Variable and from the drop-down menu we have selected the variable which in our example is Text – City Name. However, if we wanted to report the weather conditions only on a specific city then we would need to select Text as the Value type and type the exact city name in the box.
On the node, you can see the Content type and Content sections. These two areas are for cases where you have a form of content which you would like to attach to your query. For example, updating a list into SharePoint could be a use case. However, since in our example we do not intend to add any additional information to our query, we leave this section as None.
Once you have set the trigger and button name, you need to add the Variable Mapper node. In simple words, a variable mapper acts like a translator that ensures your bot speaks the same “language” as the API, making it easier to exchange information between them. In our example, The Mapper extracts and properly formats the City ID from the AccuWeather API response.
Now we need to do the setting for our Variable Mapper. The source node is API 1 since we are using the Variable Mapper to translate information from API 1 into our desired format. As for the source type, we have options to select Text, JSON, and File. Since we are not trying to extract any files, that option is omitted. We are left with two options: Text and JSON. In our tutorial, we have shown that we selected JSON and also mapped the Variables.
To explain why we did that, we select Text here instead and show you the output of the variable mapper and we go to preview and see what the Bot will return us as a result.
We enter Frankfurt as our testing city and click Get Information. You might be wondering what this strange piece of text is? In simple terms, what you see here is AccuWeather’s response to our query for the City ID in JSON form. What we need to do is convert it into a more readable format. In technical terms, this process is called flattening the JSON.
To flatten the JSON, we are going to use Extract from JSON function from Map variables. So go ahead and copy the full JSON here so we can use it on the bot. Back at our Variable Mapper node, change Source type from text to JSON. Click on Map variables and then click on Extract from JSON. Select replace all current data with extracted data and paste JSON in the box. Once you click Confirm, you’ll see that node does its magic by listing all of JSON keys and their associated variable names.
Remember that all we needed at this stage was city ID key? In our example, JSON key for city ID is Zero.Key. Feel free to rename variable name into what you prefer; delete all extra JSON keys that are not needed and click save.
With these settings in place, let’s look at what Bot will return on front end. In text node, we update Field Input and select Mapper 1.City ID. Save changes and click Preview. You can see that we have exact City ID without all strange JSON text
Up until this step, we have learned how first API Connector with help of Variable Mapper extracts right City ID for bot.
Now, we need to use this ID number to get weather information. In our tutorial, we explained that we add logical condition so that it can act as gateway allowing API node and Variable Mapper node get information for processing in the next step in a timely manner ensuring that this information is a valid input for the next nodes.
In the second API connector, we select connector Weather current data. The Value selected for connector is Mapper 1.city ID which now provides us with requested city ID which Variable Mapper then translates into the information that API 2 retrieves. The rest of this process is pretty similar to the previous stage
We have looked at how JSON can be used as Source type; in this step can see use case of Text as source type.
Since in addition to temperature, we would like to have the summary of weather conditions; we are going to use AI output to generate summary for us. Selecting Text as Source type allows us to utilize full API response which contains information such as date, weather conditions and precipitation.
The rest of Bot involves Logical condition and AI Output node elaborated on them in other tutorial videos.
We tried to make this tutorial a helpful tool in making API Connectors and Variable Mappers more understandable for you. You can find some relevant tutorials and demos linked below to further your understanding of functions of e!
