Intwixt provides a REST connector, so that your bot can make external HTTP calls. In this blog post I will create a Weather Bot that will call OpenWeatherMap.org in order to get the current weather for a particular location.
Once finished, I'll invoke my Weather Bot over HTTP to get the current weather. In a future blog post, I'll invoke my Weather Bot as a reusable module in order to provide weather functionality to another bot. This is important as it reveals just how powerful bots can become. Leverage the power of the API economy and share this capability across all of your bots as a reusable component.
Define Global Models
When calling external APIs, you need to describe the format of the data being exchanged, so Intwixt can properly generate and parse it. Because my bot will get its weather data from OpenWeatherMap, that site will strongly influence the shape of my Weather Bot's API, particularly which output fields are available (e.g., temperature, humidity, visibility, etc).
The API I will call to get the weather by latitude/longitude is documented at https://openweathermap.org/current#geo.
According to the OpenWeatherMap API docs, two query fields, lat and lon, are required to call the GEO API. However, the GEO API requires two additional fields to work properly if you read the fine print (which you often need to do when calling another service's APIs). First, OpenWeatherMap states that you need to provide a user-specific API key with every call. Without this key, the call will return a HTTP 401 Status Code (see http://openweathermap.org/appid).
In addition to the API key, it's important that our Weather Bot return the temperature in Fahrenheit or Celsius. This can be set using a field named units.
Ultimately, after a thorough reading of the OpenWeatherMap API docs, I decided that when I define the input model to contact their service, I will define four fields, namely, lat, lon, appid, and units. Refer to the following video where I use the Intwixt Data Modeler (located at https://my.intwixt.com/#/resources) to define the shape of my data when calling OpenWeatherMap.
While the input only has four fields, the output produced by OpenWeatherMap is complicated and contains both nested objects and arrays of objects. Intwixt's modeling specification is capable of modeling complex JSON models such as this, but it's often tedious to author such complexity manually. In the following video, I show how to use the sample JSON document provided by OpenWeatherMap to define the output model.
The input and output data models are defined. I can now create a Weather Bot that can use them when calling OpenWeatherMap for the weather.
Create a Generic Bot
Navigate to your bot list at https://my.intwixt.com/#/bots. Click on the menu item, CREATE BOT, and then chose Create Generic Bot.
The Create Generic Bot Dialog will load. Enter a title and description (optional), and then click CREATE.
Add an HTTP Receiver
Add an HTTP Receiver trigger to your bot. This will allow you to contact it as a RESTful API Endpoint. (When you provide latitude and longitude, it will respond with the weather.) Begin by clicking the plus sign (+) in the upper left to create a trigger. Choose HTTP Receiver as its type (Option 1).
Define the API Signature
The HTTP Receiver needs to define a model for its input and output, so callers know its signature. This is done using data models. For this example, I'll define a new local model for the input. It will include lat, lon, and units (metric or imperial). I'll use the global model, Weather Output, that I defined above for the output.
Add a Bot Property
When calling OpenWeatherMap, my bot will need to provide an API key which I already applied for. In the following video, I embed my OpenWeatherMap API key as a Bot Property, so I can reference it as a variable within my bot. This has the benefit of keeping the key out of sight and making it easy to change globally if necessary.
Add an HTTP GET Activity
It's now time to add our HTTP GET activity and call OpenWeatherMap to get the weather. The following video shows this process. I start by adding a REST activity and configuring it to provide the proper input data to OpenWeatherMap. I conclude by adding a response activity.
Test The API
Intwixt provides several methods for testing an API. In the following video, I use the API Test Utility embedded within the Intwixt Designer. Combining this tool along with the Activity Log helps you understand whether or not your bot successfully executed as you are able to review the step-wise series that are executed by your bot.
REFINE And Test The API
I will eventually call my Weather Bot from other bots I create (bots can invoke other bots). I also need to make my Weather bot available as an API GET call (not HTTP POST). This means I need to modify the path, method, and signature as shown in the following video.
In order to specify that a field should be passed as a query parameter, you must include "+query" in the data model. This ensures that the API Parser checks the proper location when handling the API call. Take special note that I restart my Weather Bot at the end of the video, since I change its API to HTTP GET and modify its path.
I'll now test my Weather Bot over HTTP, using the Intwixt API Explorer. I'll use San Francisco's Latitude and Longitude as the input. I'll specify imperial (Fahrenheit) as the units.
Defining data models is a critical first step when calling external APIs. Intwixt provides several tools to simplify defining and refining data models. Once you've defined a data model, you can use it when calling external RESTful APIs. This allows you to integrate external APIs into your bot to extend your bot's functionality.