API request

Queries third-party software through its web interface during the call, stores the response in variables, and takes the Error output as soon as it takes too long or fails.

In brief

The help text shown in the window is: "Queries an HTTP API and extracts JSON values into variables. If the API fails or exceeds the timeout, the 'Error' output is taken. Use {{variable}} in the URL, headers and body."

How it works

What an API is

An API is a piece of software's service window: a web address that another program queries, and which responds not with a page to read, but with structured data. Most respond in JSON, a format that organizes information by name, like a form: {"customer": {"name": "Smith", "status": "premium"}}.

The module sends the request, reads the response and extracts what interests you.

Variables in the request

The URL, the Headers and the Body accept {{variable}} entries, replaced right before sending. This is how you query the service about the current caller: https://api.example.com/customer/{{caller}}.

Extraction

The response is rarely to be taken as a whole. The table at the bottom links a JSON path to a Variable name. The path reads from the outside in, with levels separated by dots: customer.name goes to fetch name inside customer. A list is browsed by its index, starting at zero: 0.name refers to the name of the first element.

A path left blank returns the entire response: this is what you need when the service responds directly with a number or a word, with no structure around it.

A path that leads nowhere gives an empty variable, with no error. The OK output is still taken, since the service did respond.

When the Error output is taken

• the URL is empty;
• the service does not respond within the delay;
• it responds with an error code, meaning any code outside the success range;
• the circuit breaker is open.

The circuit breaker

A service that's down should not slow down all your calls. After 5 consecutive failures toward the same server, the module stops calling it for 30 seconds: the Error output is taken immediately, without waiting for the delay and without even sending the request. A first success resets the counter to zero.

This is a safeguard, and it explains a puzzling observation: during those thirty seconds, the call comes back Error in a flash, even though the service may already be back up.

What to fill in

The Add an extraction button creates a row, Delete removes its own, Save closes the window.

Steps

1. Get from your provider the address to query, how to authenticate, and a sample response. Without a sample response, you won't be able to write the extraction paths.
2. Place the API request module and connect the previous node to its input.
3. Open it, choose the Method and set the Timeout as short as your service can support.
4. Enter the URL, inserting variables from the Available variables panel.
5. Fill in the Headers, one per line, generally the authentication line provided by the vendor.
6. For a POST or a PUT, enter the Body.
7. Click Add an extraction and pair a JSON path with a Variable name, as many times as there are values to retrieve.
8. Click Save, then connect OK to the normal path and Error to a fallback that handles the call without the data.
9. Place a Debugging module after the OK output, with the extracted variables as its message, to read what was actually received.
10. Click Save, then Apply changes in the top banner.
11. Call your number, then open the plan's Debug log and check the extracted values.

If it doesn't work

All calls come back Error even though the URL works in a browser. A browser sends your session cookies, the module does not. Check the authentication header. Then check the URL once variables are replaced: a misspelled {{name}} becomes blank and produces an incomplete address. Finally, any response outside the success range counts as a failure, including a readable error page.

The Error output is taken instantly, without the service being called. The circuit breaker is open: five consecutive failures toward this server tripped it for thirty seconds. Wait half a minute before concluding, then call again.

I chose 10 seconds and the call moves on after 8. The delay is capped at eight seconds at run time, whatever value you chose. This is intentional: beyond that, the caller has already hung up.

The extracted variable is empty even though the response contains the data. The path doesn't match. Levels are separated by dots, lists are counted from zero, and an empty path returns the entire response. First extract the whole response into a variable, read it in the Debug log, then write the exact path.

The call cuts off when the service doesn't respond. The Error output is not connected to anything. Connect it, at minimum toward the usual greeting.