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
-
Drag an HTTP Node into your workflow.
-
Set the Request URL to your API endpoint (e.g.,
https://api.example.com/devices
). -
Select the HTTP Method:
GET
,POST
,PUT
, orDELETE
. -
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
jsonCopyEdit{
"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:
{
"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
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.