Using Variables in KurocoEdge – API Variables

info

Estimated required time：15 min

Overview

KurocoEdge allows you to define API variables within a Rule's Action. These API variables can be reused within current or any following Action's 'Execution' section, with the {$variable} syntax.

What You Will Learn

• Where to Define an API Variable
• Configure an Action's 'Execution' Settings
• Test if the Variable is Working

Where to Define an API Variable

Within the 'Conditions / Variables' section of an Action, click 'Add Item' to create a new item. In the select/dropdown item that appears, choose the 'API variable' option.

Next, click the [Add API] button, then click [Edit] to configure the API Variable settings in a modal popup window.

In the 'API Variable > Settings' tab, the first step is to enter in the API endpoint you wish to use:

caution

In order for this API endpoint to work as intended, it must first be added to the 'Backend list' section (which is a 'whitelist' of backend hosts that KurocoEdge can use). It is important to enter it using the correct format, and not include 'http://' or 'https://' before the rest of the URL.

In this tutorial, we will use the sample API jsonplaceholder.typicode.com, which is a free online API that provides dummy JSON data.

API Endpoint Should be an Object

An important point to note is that many API endpoints will return an array of objects. A basic requirement of API Variables is that the API response must be an object at the root level.

caution

Api response having a JSON Array at root level will always result in an error.

Instead of using a resource like jsonplaceholder.typicode.com/users – which will return an array of user objects – we can access a specific resource such as jsonplaceholder.typicode.com/users/1. This will return the following object for a single user:

{
"id": 1,
"name": "Leanne Graham",
"username": "Bret",
"email": "Sincere@april.biz",
"address": {
  "street": "Kulas Light",
  "suite": "Apt. 556",
  "city": "Gwenborough",
  "zipcode": "92998-3874",
  "geo": {
    "lat": "-37.3159",
    "lng": "81.1496"
    }
  },
"phone": "1-770-736-8031 x56442",
"website": "hildegard.org",
"company": {
  "name": "Romaguera-Crona",
  "catchPhrase": "Multi-layered client-server neural-net",
  "bs": "harness real-time e-markets"
  }
}

Entering in Expected Variables

As we can see, one of the top-level variable names in this response object is username (with a string value of Bret).

We can now enter this variable name into the 'Expected variable(s)' section field, and rename it to any string value we want. In our case we will rename it to renamed_username:

'API endpoint' and 'Expected variable(s)' are the only required fields in the settings for this API Variable. You can configure the remaining settings as you wish:

Field	Value
API endpoint	jsonplaceholder.typicode.com/users/1
Cache	1minute(s)
Method	'GET'
Preload	false
Headers
Expected variable(s)	'Variable name in API response': username, 'Rename': renamed_username
Request cookies to be forward to the API
Cookies returned by API Response for forwarding

Configure an Action's 'Execution' Settings

After you have configured the settings as desired, you can use the renamed variable (in our case renamed_username) in the 'Execution' section of our Action.

To demonstrate how to do this, we will set up a new header - which we will name test_header - and give it the value of our variable using standard the {$variable} notation for variables in KurocoEdge. In our case this will be {$renamed_username}:

Test if the Variable is Working

After clicking [Update], then [Preview], and navigating to the 'Headers' tab under 'Network' in the Developer Console in our browser, we should now be able to see the test_header in our Response Headers section, with the correct value of Bret being displayed:

Accessing Nested Values in an Object

If the value of the API variable you have assigned is not a simple string, number, or boolean – but rather an object with nested key/value pairs – it is necessary to access these nested values using dot notation.

For example, let's look at an object address within an sample API response fetched from https://jsonplaceholder.typicode.com/users/1:

"address": {
  "street": "Kulas Light",
  "suite": "Apt. 556",
  "city": "Gwenborough",
  "zipcode": "92998-3874",
  "geo": {
    "lat": "-37.3159",
    "lng": "81.1496"
    }
  }

If we follow the same steps above, but instead rename the address value to renamed_address in 'Conditions / Variables', we can access this object in the 'Execution' section of our Action, using the same {$variable} notation.

In our case, it would be {$renamed_address}. To display this variable, we can set it as the value of a header, which we will call test_header:

After clicking [Update], then [Preview], and navigating to the 'Headers' tab under 'Network' in the Developer Console in our browser, we should now be able to see the test_header in our Response headers with the value being our API Variable we named renamed_address.

However, because it is not possible to display an object as a value for a header, it should show the value {$renamed_address} as a string instead:

This is not our intended usage, but merely to demonstrate what will happen. In order to instead access nested values within the renamed_object variable, we need to return to the Execution tab in the Action, and use dot notation.

If we want to access the nested value of street (within the address object), we can once again update the variable name to {$renamed_address.street}:

After clicking [Update] and refreshing our page in Preview mode in the browser we should see the correct value displayed (in our case the value of address.street is the string Kulas Light):

This confirms that the intended value is being displayed properly and is now working in our Action as intended.

The root level element should be an object, however nested elements might be JSON Arrays. Navigating the arrays is possible using .n notation. For example, to get the first user's name of the API response below, we would write {$users.0.name}, which would display John (considering users has been set as Expected Variable)

"users": [
  {
    "name": "John"
  },
  {
    "name": "Maria"
  }
]

Related documentations

• Managing meta tags using MicroCMS and KurocoEdge
• Managing meta tags using WordPress and KurocoEdge