Using External APIs in Workflows (Input + Output)

Integrating third-party systems is essential for building powerful and connected applications in Rayven.io.

Integrating third-party systems via APIs is essential for building connected, intelligent applications in Rayven.io. Rayven workflows support both inbound API calls (HTTP requests to external services) and outbound API publishing (exposing workflow data to be pulled by external platforms).

This article covers how to:

  • Use HTTP Request Nodes for external API integration

  • Handle authentication and response parsing

  • Configure retry logic and error handling

  • Publish data through Output APIs in JSON, CSV, or XML


Part 1: Making Outbound Requests to External APIs

Overview

The HTTP Request Node allows Rayven workflows to interact with external systems over RESTful APIs. Use cases include:

  • Sending alerts or sensor values to CRMs

  • Fetching external analytics

  • Pushing data to ERPs or cloud platforms

  • Requesting updates from third-party devices


Configuring an HTTP Request Node

Basic Setup

  1. Drag an HTTP Node into your workflow.

  2. Set the Request URL to your API endpoint (e.g., https://api.example.com/devices).

  3. Select the HTTP Method: GET, POST, PUT, or DELETE.

  4. Add any query parameters, headers, or body needed for the request.


Injecting Dynamic Fields

You can insert live workflow variables into:

  • URL path parameters: e.g., .../device/

  • Headers: e.g., Authorization: Bearer

  • Payloads: e.g., { "temperature": , "status": "" }

This allows your requests to adapt dynamically at runtime.


Authentication Options

Rayven supports multiple forms of API authentication:

  • API Key in Headers

    json
    CopyEdit
    {
    "Authorization": "Bearer ",
    "Content-Type": "application/json"
    }
  • Basic Auth
    Enter the username and password directly into node configuration.

  • OAuth2
    Token generation must occur upstream. The acquired token can then be injected into the HTTP node via a variable.


Parsing API Responses

HTTP nodes return full response data, including:

  • statusCode

  • headers

  • body (typically JSON)

Use Expression or Conditional Nodes to:

  • Extract values:

  • Check response status: statusCode == 200

  • Route logic based on response fields

Example Response:

json
CopyEdit
{
"temperature": 23.4,
"humidity": 64,
"status": "ok"
}

Error Handling Strategies

To improve resilience:

  • Use Conditional Nodes to validate response status.

  • Add retry logic (e.g., up to 3 attempts with 5-second delays).

  • Log failures to a Rayven table for audit.

  • Build fallback paths in workflows when APIs are unreachable.


Monitoring API Interactions

  • Open the Debugger Panel to inspect:

    • Request headers/body

    • Response codes and data

  • Use UID filters and date ranges for targeted review.

  • Visit the Analytics tab to track frequency, failure rates, and performance.


Best Practices

  • Test with mock data before live deployment.

  • Secure sensitive tokens with encrypted variables.

  • Use clear naming for all API nodes and outputs.

  • Include fallback routes and rate-limit protection.

  • Document the API's behavior in workflow notes for team visibility.


Part 2: Publishing Data via Output API (Data Pull)

Rayven also allows external systems to pull data directly from workflows via the Output API configuration.


Configuring Output API Publishing

Use the Output API node to expose workflow results as an external endpoint. Rayven will handle the formatting and serve the data via a pull URL.

Required Settings:

Field Description
Node Name* Name for internal identification
Password Authentication for the API pull
URL* Auto-generated Rayven endpoint (e.g., https://my.rayven.io:8082/api/apipull?...)
IP Restrictions (Optional) Limit access to specific IP ranges
Pass Data as Received Toggle to forward raw input values
 

Payload Format Options

Choose from three supported outbound formats:

  • JSON

  • CSV

  • XML


Field Configuration

Define the structure of the returned data using columns:

Column Field Description
1 Data Field Name: device_id Dynamically sourced from workflow variable
2 Data Field Name: Event Date Mapped from event timestamp
3+ Any number of additional fields, mapped to workflow variables  
 

You can specify:

  • Display Names for the output columns

  • Field Selection type (workflow variable, date, or static)


Sample Output URL

plaintext
CopyEdit
https://my.rayven.io:8082/api/apipull?uid=xxxx&deviceid=[[device_id]]

External platforms can use this endpoint to fetch structured, up-to-date workflow results in real time.


Q&A

Q: Can I trigger a workflow using an external API call?
A: Yes. Use an HTTP Listener Node to expose a Rayven endpoint that external systems can POST to.

Q: How do I authenticate incoming or outgoing API calls?
A: Use headers for token-based auth, Basic Auth for username/password, or configure IP-based restrictions for Output APIs.

Q: Can I expose multiple fields in an Output API?
A: Yes. Add as many columns as needed to your Output API node, and map each to a workflow field or static value.

Q: What happens if the API call fails?
A: Use retry logic, fallback branches, and logging to detect and recover from errors. Always validate status codes before continuing.

Q: Can I serve both JSON and CSV from the same workflow?
A: Not from a single node, but you can configure multiple Output API nodes—one per format—and expose them via different URLs.

Q: Is the Output API pull real-time?
A: Yes. It serves the most recent values stored at the time of request, based on the configured data pipeline.