The API call actions allow you to interact with any REST or GraphQL API to send or get data from an external system.

In this article we'll go over how API call actions can be configured:

Choose the type of operation you want to perform (get or send data)
With headers that contain metadata
Store response values in data points with JSON path and use it to enrich your workflow

Get or send data

There are two main types of operations you can perform against an API: getting data out of a system or pushing data into a system. The latter is often also used to perform external actions in a system.

Awell Studio allows you to interact with 2 types of APIs: REST and GrahQL. There are a couple of differences between the two like REST has HTTP verbs (GET, POST, ..) whereas GraphQL has different types of operations (queries, mutations, ...) but configuring them should be relatively straightforward via the UI.

Configure headers

Headers can be used to attach metadata to an API call and are often used for authorization purposes (eg: adding an API key). Headers can easily be added through the GUI.

Populate the request body

The request body holds the core information you want to send or retrieve from the server. It can be the main content of your API call and is formatted as a JSON. To use the request body, make sure that it is in JSON format before sending your request.
If you want to send an empty request, just put {} within the body tab. A non-empty body request would like {"data" : "option1"}

Store response values in data points with JSON path

One of the most powerful aspects of the API call action is the ability to store response values from an API in a data point. When the value is stored in a data point, it can be used in conditional logic, reports, calculations, ...

To access data from the response and store the value in a data point, we use JSON path which is a query language for JSON objects.

We'll provide a couple of examples below but we invite you to have a look at below resources to get familiar with JSON path:

Important notes

Please note that JSON path expressions always return an array. When you store a response value in a data point of type string and your expression yields more than one result, by default we will store a stringified and comma-separated version of the result. If you'd like to store the first match only, make sure to check the "Store first match only" checkbox.

For data points of type string you can choose to either store the first match of your JSONPath expression or a comma-separated string of all matches.

For all other data point types, we will only store the first element of the array.

Have a look at the examples below to get a better understanding how data can be stored with JSON path expressions.

Example 1

Response:

{
  "data": {
     "appointment_date": "2022-05-05"
  }
}

JSON path:
$.data.appointment_date

Outcome:
2022-05-05 will be extracted from the response and stored as the value for your data point.

Example 2

Response:

{
  "data": {
    "form": {
      "answers": [
          {
            "id": "question_1",
            "value": "an answer"
          },
          {
            "id": "question_2",
            "value": "another answer"
          }
        ]
    }
  }
}

JSON path:
$.data.form.answers[?(@.id == "question_1")].value

Outcome:
an answer will be extracted from the response and stored as the value for your data point.

Example 3

Response:

{
  "data": {
    "tags": [
        {
            "label": "tag-1"
        },
        {
            "label": "tag-2"
        }
    ]
  }
}

JSON path:
$.data.tags..label

Outcome:

If "Store first match only" is checked: tag-1 will be extracted from the response and stored as the value for your data point.
If "Store first match only" is unchecked: tag-1,tag-2 will be extracted from the response and stored as the value for your data point.

Example 4

Response:

{
  "data": {
    "ages": [
        {
            "age": 24
        },
        {
            "age": 34
        }
    ]
  }
}

JSON path:
$.data.ages..age

Outcome:
24 will be extracted from the response and stored as the value for your data point.

Create your own form

Dynamize your actions with variables

Set up a GraphQL API call action with Healthie