Working with the API

Overview

So far, we have created the bot with enough functionality to ask the user for a zip code and send a reply in case the user's input is not adequate.

However, if the user's feedback is correct and the zip code valid, we cannot process it. That's what we are going to do throughout this chapter.

Getting the API key

To retrieve the data and information related to the zip code, we need to invoke the Zipcodebase API.

To use Zipcodebase, we need to call the API using an API key. Switching back to the Zipcodebase web page, let's copy the value under API Key from the Dashboard.

Figure 4-a: Zipcodebase Dashboard with API Key

HTTP request

Going back to Composer, in the bot explorer, make sure that the BeginDialog is selected. Then below all the existing actions added, click + > Access external resources > Send an HTTP request.

Figure 4-b: Composer – BeginDialog – Access external resources – Send an HTTP request Menu Item

The following details are visible in the properties pane. Select the GET option under the HTTP method.

Figure 4-c: Composer – BeginDialog – Send an HTTP request – HTTP method

At this stage, we need to get the API URL, which we can get from the Zipcodebase website as highlighted in the following figure.

Figure 4-d: Zipcodebase – API URL

The following is the Composer-compatible version of the URL, because the user.zip variable contains the zip code submitted by the user.

https://app.zipcodebase.com/api/v1/search?codes=${user.zip}

Next, we need to add the API key to the URL and the country code. So let's copy the API Key value from the Zipcodebase website to add it to the URL.

Figure 4-e: Zipcodebase Website API Key Value

In the following URL, replace API_KEY_VALUE_GOES_HERE with the value of your API key copied from the Zipcodebase website.

https://app.zipcodebase.com/api/v1/search?apikey=API_KEY_VALUE_GOES_HERE&codes=${user.zip}&country=US

Enter the URL into the Url field within the properties pane of Composer, as shown in the following figure.

Figure 4-f: Composer – BeginDialog – Send an HTTP request – Url

When the bot performs the HTTP request, the response must be stored somewhere—in a variable assigned to the Result property.

We will store the result within the dialog.api_response variable. The dialog is a scope that retains its properties for the duration of a dialog, in this case, BeginDialog.

Tip: To understand how properties and variable scopes work, I suggest looking at the official documentation.

Figure 4-g: Composer – BeginDialog – Send an HTTP request – Result property

Next, we need to set the Response type value to json.

Figure 4-h: Composer – BeginDialog – Send an HTTP request – Response type

HTTP status code

When working with HTTP requests, status codes are essential. Status codes indicate whether the request was successful or not.

Therefore, the bot must determine whether the response was successful before sending a response to the user.

A status code with a value of 200 indicates that the response obtained from the API was successful. A status code with a different value would suggest a problem accessing the API—in a situation like this, we need to create a branch.

Creating a branch

To create a branch—which in programming would be the equivalent of using an if-else condition—we need to go back to the authoring canvas and click + under Send an HTTP request. Then, click Create a condition > Branch: If/else.

Figure 4-i: Composer – BeginDialog – Create a condition – Branch: If/else

The Branch: If/else appears in the authoring canvas. Select the branch, and in the properties pane, under Condition, select the Write an expression option.

Figure 4-j: Composer – BeginDialog – Branch: If/else – Condition – Write an expression

As the Condition, set the value to: dialog.api_response.statusCode == 200.

Figure 4-k: Composer – Begin Dialog – Branch: If/else – Condition

Under the True branch, click +.

Figure 4-l: Composer – BeginDialog – Branch: If/else – True Branch

Once that is done, click Manage properties > Set properties.

Figure 4-m: Composer – BeginDialog – Branch: If/else – Manage properties – Set properties

You will then see the following.

Figure 4-n: Composer – BeginDialog – Branch: If/else – True Branch – Set properties

We will use the Set properties action because we want to assign the response values obtained from the API to a few variables. This way, the results are provided to the user with the requested zip code information.

Querying the API

Before proceeding, we need to check which values the API can return. To do that, let's use Hoppscotch, which is an open-source API development web application that allows you to query and interact with any REST API.

So, point your browser to the Hoppscotch website (I usually use either Microsoft Edge or Google Chrome, but feel free to use another modern browser). Add the following URL to the field highlighted in the screenshot below.

https://app.zipcodebase.com/api/v1/search?apikey=API_KEY_VALUE_GOES_HERE&codes=33165&country=US

Make sure you replace API_KEY_VALUE_GOES_HERE with the value of your Zipcodebase API Key. For testing purposes, I've replaced ${user.zip} with 33165.

Figure 4-o: Hoppscotch Website Querying the Zipcodebase API

With the URL pasted, you can test the API by clicking Send. Let’s see what happens.

Figure 4-p: Hoppscotch Website – Zipcodebase API Query Raw Results

As seen in the preceding figure, the API returns a result. To see the result in full detail, click the JSON tab. In most cases, when using the Hoppscotch website, the JSON tab will be the default tab.

Figure 4-q: Hoppscotch Website – Zipcodebase API Query JSON Results

By inspecting the result returned by the API, we can find two distinct sections: the query and results sections. We want to get the data from the results section.

Notice that the results JSON object contains another JSON object with the zip code value (33165) passed as a query parameter to the API call, which is an array of JSON objects with one element in this case.

First assignment

For each of those values contained within that array element, we want to create a property and assign its respective value so that the bot can return them to the user as a response.

To do that, go back to Composer, make sure that the Set properties action is selected, and then within the properties pane, click Add new under Assignments.

Figure 4-r: Composer – BeginDialog – Set properties – Assignments – Add new

Let's add dialog.postal_code as the Property name.

Let’s also add dialog.api_response.content.results[user.zip][0]['postal_code'] as the Value, as seen in the following figure.

Figure 4-s: Composer – BeginDialog – Set properties – Assignments – Property/Value

So, let's analyze what we have just done here. We are going to store the zip code returned by the API call within the dialog.postal_code variable. The zip code returned by the API is accessible using dialog.api_response.content.results[user.zip][0]['postal_code'].

But how did I reach the conclusion that the zip code returned by the API is available through dialog.api_response.content.results[user.zip][0]['postal_code']? To understand this better, let's have a look at the following diagram.

Figure 4-t: Relationship between the API Response and Assignments Value

We can see that dialog.api_response corresponds to the complete response (highlighted in purple) returned by the API, including the header and Response Body.

Contained within the Response Body, we find the content highlighted in green.The content includes a query and a results object. Within the content object, highlighted in orange-yellow, we see the results object.

Within the results object, we find another object (highlighted in light blue) that contains an array, and this object has the same value as the zip code queried (which we previously stored in the user.zip variable).

Finally, within the array's first element ([0]), highlighted in red, we find each of the properties. We want to retrieve the value of the postal_code property.

Other assignments

Now that we have assigned the value of the first property (postal_code) returned by the API call, let's do the same for the other properties returned by the API.

All we need to do is click Add new for each property we want to add from the results object.

By using dialog.api_response.content.results[user.zip][0]['country_code'], we can retrieve the value of country_code. Store it as dialog.country_code.

Figure 4-u: Composer – The dialog.country_code Property

Likewise, with dialog.api_response.content.results[user.zip][0]['latitude'], we can retrieve the value of latitude. Store it as dialog.latitude.

Figure 4-v: Composer – The dialog.latitude Property

With dialog.api_response.content.results[user.zip][0]['longitude'], we can retrieve the value of longitude. Store it as dialog.longitude.

Figure 4-w: Composer – The dialog.longitude Property

With dialog.api_response.content.results[user.zip][0]['city'], we can retrieve the value of city. Store it as dialog.city.

Figure 4-x: Composer – The dialog.city Property

With dialog.api_response.content.results[user.zip][0]['state'], we can retrieve the value of state. Store it as dialog.state.

Figure 4-y: Composer – The dialog.state Property

With dialog.api_response.content.results[user.zip][0]['city_en'], we can retrieve the value of city_en. Store it as dialog.city_en.

Figure 4-z: Composer – The dialog.city_en Property

With dialog.api_response.content.results[user.zip][0]['state_en'], we can retrieve the value of state_en. Store it as dialog.state_en.

Figure 4-aa: Composer – The dialog.state_en Property

With dialog.api_response.content.results[user.zip][0]['state_code'], we can retrieve the value of state_code. Store it as dialog.state_code.

Figure 4-ab: Composer – The dialog.state_code Property

With dialog.api_response.content.results[user.zip][0]['province'], we can retrieve the value of province. Store it as dialog.province.

Figure 4-ac: Composer – The dialog.province Property

With dialog.api_response.content.results[user.zip][0]['province_code'], we can retrieve the value of province_code. Store it as dialog.province_code.

Figure 4-ad: Composer – The dialog.province_code Property

Note: Each Value field starts with a = character, whereas the Property fields do not.

Tip: It is not necessary to save each value returned by the API, just the ones that your bot will use. In this case, I've opted to store each value returned by the API call to highlight how to do it.

Summary

Our bot is not ready yet. Nevertheless, the goal of this chapter was to explore how to interact with the API, obtain a response, and store each response value, which we have done.

In the chapter that follows, we will add the remaining steps to finalize the creation of our bot.