REST API Instruction Type | Yext Hitchhikers Platform

A REST API step can be used to read or write data from a REST API, often using data collected from previous steps (though not always). A REST API step requires the following configuration:

method - the HTTP verb, either GET, POST, PUT, PATCH or DELETE.
url - the URL of the API.
headers - (optional) HTTP headers for the request.
body - (optional) JSON body for a POST request.

Using Collected Data

It’s very common to use data collected from previous steps in the URL, headers, or body of a REST API request. For example, you might want to collect the user’s city of residence and then send an API request looking up the weather in that city.

You can do this by referencing collected in either the URL, params, or body of the request like so: [[ collectedData.theFieldId ]]

Here’s an example that combines a collect, a restApi, and a reply step:

{
  "goal": "Get the weather in a city.",
  "examples": [
    "How's the weather like",
    "What's the weather in Brooklyn right now?",
    "What's the weather in NY?",
    "How's the weather in San Francisco?",
    "What's the weather in Los Angeles?",
    "What's the weather in San Diego?"
],
  "instructions": [
    {
      "collect": {
        "instruction": "Ask the user what city they're interested in",
        "fields": [
          {
            "fieldType": "STRING",
            "id": "city",
            "optional": false
          }
        ]
      }
    },
    {
      "restApi": {
        "method": "GET",
        "url": "http://api.openweathermap.org/geo/1.0/direct",
        "params": {
          "q": "[[ collectedData.city ]]",
          "appId": "<YOUR_API_KEY>"
        }
      }
    },
    {
      "reply": {
        "instruction": "Based on the response, tell them the weather in that city. You must ALWAYS respond in Fahrenheit. You may convert the temperature from Kelvin/Celsius to Fahrenheit if needed.",
        "mode": "DIRECT_ANSWER"
      }
    }
  ]
}

In this example, we look up the weather in a given city by first collecting the name of the city as the city field, then we send it to the OpenWeather API by referencing the collected data via the syntax [[ collectedData.theFieldId ]].

Back

< IF (Conditional) Instruction Type

Function Instruction Type >

Feedback

<% elem.innerText %>