You can use the Logic Library to suspend a survey and execute an API call via HTTP/HTTPS to a remote server.
This can be done using either the "API Integration" element in the Survey Editor or the "api" logic node in the survey XML.
Note: Using the Decipher API requires users with shell access to whitelist survey URLs. Contact your Project Manager or the Decipher Support team to initiate.
Using the Survey Editor
To add an API Call using the Survey Editor, click "+ Add Survey Element" under the staging area:
In the Element Library, click "Custom" and select the "API Integration" element. Then click "Insert":
The new element will appear in the staging area, where you can configure the API call parameters:
URL: The base URL on the remote endpoint.
Method: The API call type. Can be set to GET, POST, PUT, or DELETE.
Parameters: The call parameters.
Data: Any additional payload data.
Using the XML
There are two steps you will need to follow when formatting any API call:
- Create a variable that will define the call parameters. Call parameters include what gets passed in the URL (in the GET request).
- Write the following exec code, specifying a
labelfor your API call, along with your preset variable name (
api:params) and its URL (
<exec> <logic uses="api.1" label="xxxx" api:params="yyyy" api:url="http://api.exampledomain.com" /> </exec>
The following parameters can be passed using the API logic node:
||This attribute is required and is the base URL to access. The hostname must exist in the
||This attribute is optional. It is the name of a variable that contains the URL parameters and must be a dictionary. For example, if you specify
||This attribute is the same as
||This attribute specifies the call method. It can be set to
||This attribute is optional. It allows you to pass through custom headers for your call.|
Tip: The Logic Library is continually growing and new logic nodes are being added all the time. If you are looking for more functionality with your call, contact your support team to inquire about development of new custom logic nodes for specific API calls.
Once you execute the code above, your survey will be suspended and you can check your variable name on the next page for the HTTP status code.
Interpreting Call Results
To determine whether your API call was successful, you will want to check your
node.r values. The node:status value will be your HTTP status code. If your API call is successful, you should see a status code of "
200" here. If the server responds with any other code, there are likely errors in your call; for example, an invalid URL will result in a "
500" status code.
If you receive an error code, you will want to check both your logic syntax and the results of the call.
Note: If you are running simulated data,
node.status will return
node.r value will be the response value of your call. If the API call returned JSON data, this is automatically decoded. Otherwise, you should see raw text here. If your call was successful, you will not need to do anything; the request and response will be logged automatically.
If you wanted to open a page in your survey that showed the weather in respondents' current locations, you might use the following code (where the
q is the respondent's response to "q" - a survey question asking them "In what city do you currently reside?"):
<exec> weather_data = dict(q=city.val) </exec> <logic uses="api.1" label="weather" api:params="weather_data" api:url="http://api.openweathermap.org/data/2.5/weather" /> <exec> if weather.status == 200 and weather.r["cod"] == 200: p.temperature = str(weather.r["main"]["temp"] - 273.15) else: p.temperature = None </exec>
Each API may have a different way of returning errors, and OpenWeather will have a "
cod" field in place of the "
node:status" value with either "
200" or another status code. Similarly, instead of "
node:r", this call will show The
weather.r as will be the result.
Note: OpenWeather also returns the temperature in Kelvin, rather than Fahrenheit or Celsius.