External API Power

Overview

When writing your skills, you may want to obtain data that doesn't exist in PrecisionLender, such as from an external API source. In this article, we'll discuss how to use the external API powers when writing your skills.

In this Article

• What are the external API powers?
• How to call the external API powers

What are the external API powers?

The external API powers allow you to return a promise using either the 'get' or 'post' methods based on the defined parameters.

• get (url, headers) - returns a promise that once the call is complete, the object received from the 'get' request will be returned

  • url - entered as a string, is a parameter that defines the https source for the call. This parameter must be defined.
  • headers - entered as any data type, is a parameter that defines the header values for the request. This is an optional parameter. If not defined, enter 'null'. 
    • For example if your API endpoint uses a basic authentication to allow any get operation then it could be passed within the headers e.g.:

      let headers: any = { Authorization: "Basic <yourtokenhere>"}

• post (url, headers, data) - returns a promise that once the call is complete, the object received from the 'post' request will be returned

  • url - entered as a string, is a parameter that defines the https source for the call. This parameter must be defined.
  • headers - entered as 'any' type, is a parameter that defines the header values for the request. This is an optional parameter. If not defined, enter 'null'. 
    • For example if your API endpoint uses a basic authentication to allow any get operation then it could be passed within the headers e.g.:

      let headers: any = { Authorization: "Basic <yourtokenhere>"}

  • data - entered as 'any' type, is a parameter for the JSON post body for the request. This parameter must be defined.

How to call the external API powers

The API powers will be called via the request property of the Andi® powers.

//get
return skillContext.powers.andi.request.get()

//post
return skillContext.powers.andi.request.post()

Here's an example run code for a skill that uses the 'get' method to obtain weather data from an external API. Notice how in this example, the API url is defined as a string in a variable, and then the variable is passed in as the url parameter. 

export function run(skillContext: andiSkills.ISkillContext): andiSkills.RunResponse {
    // this is a sample zipcode for testing
    let zip: string = "94040";
    let weatherApiUrl: string = `http://samples.openweathermap.org/data/2.5/weather?zip=${zip},us&appid=b6907d289e10d714a6e88b30761fae22`;
    // get the weather data from external api
    return  skillContext.powers.andi.request.get(weatherApiUrl, null)

Once the promise is returned, if there is weather data that is returned, then the data is defined as a custom value for and displayed in a field tag. 

export function run(skillContext: andiSkills.ISkillContext): andiSkills.RunResponse {
    // this is a sample zipcode for testing
    let zip: string = "94040";
    let weatherApiUrl: string = `http://samples.openweathermap.org/data/2.5/weather?zip=${zip},us&appid=b6907d289e10d714a6e88b30761fae22`;
    // get the weather data from external api
    return  skillContext.powers.andi.request.get(weatherApiUrl, null)
                .then((result) => {
                    let weatherForecast: string = "";
                    if(result && result.weather && result.weather[0] && result.weather[0].description)  {
                        weatherForecast = result.weather[0].description;
                    }

                    // send a field tag information with current weather forecast
                    // this field tag will only show when weatherForecast has some value
                    return skillContext.powers.andi.fieldTag.sendFieldTag(
                        andiSkills.FieldTagTypes.Warning,
                        "current-weather-info",
                        1,
                        "Current forecast for zipcode " + zip + ": " + weatherForecast ,
                        null,
                        null,
                        function (api, model, comparehash, custom) {
                            // use the custom value passed in to show or hide field tag
                            if (custom.weatherForecast && custom.weatherForecast.length > 0) {
                                return true;
                            }
                            return false;
                        },
                        null,
                        null,
                        {
                            // pass the local custom value into Andi context
                            weatherForecast: weatherForecast
                        }
                    );
                });
}