API Request Node

Overview

The API Request Node enables integration with external services through HTTP/HTTPS requests. This node supports various request methods, authentication mechanisms, and response parsing capabilities to seamlessly connect your Gravia workflows with third-party APIs and web services.

Usage cost: 1 credit

Configuration

Settings

1. Request Configuration

   • Method: HTTP method to use (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)

   • URL*: Target endpoint for the API request

     • Supports variable interpolation (e.g., https://api.example.com/users/{user_id})

     • Must include protocol (http:// or https://)

2. Headers

   • Key-value pairs for HTTP headers

   • Common examples: Content-Type, Accept, Authorization

   • Supports variable interpolation in both keys and values

3. Query Parameters

   • Key-value pairs appended to the URL

   • Automatically URL-encoded

   • Supports variable interpolation in both keys and values

4. Request Body (for POST, PUT, PATCH, DELETE methods)

   • Body Format: Determines how the request body is formatted

     • JSON: Structured data in JSON format

     • Form Data: Multipart form data

     • URL Encoded: Form data as URL-encoded string

     • Raw: Plain text content

     • Binary: Binary data

   • Body Content: The actual content to send

     • Supports variable interpolation

     • For JSON, must be valid JSON syntax

5. Authentication

   • Authentication Type:

     • None: No authentication

     • Basic Auth: Username/password authentication

     • API Key: Key-based authentication

     • OAuth 2.0: Token-based authentication

   • Auth Configuration (varies by type):

     • Basic Auth: Username and password

     • API Key: Key value, placement (header, query, body), parameter name, optional prefix

     • OAuth 2.0: Grant type, client credentials, token URLs, scopes, tokens

6. Response Mapping

   • Extracts data from responses into named variables

   • Variable Name: Name to assign to the extracted value

   • Data Source: Where to extract data from (body, header, status)

   • Path Expression: JSONPath (for JSON), XPath (for XML), or header name

   • Response Format: Format of the response (JSON, XML, text)

   • Default Value: Fallback if extraction fails

7. Advanced Settings

   • Timeout: Maximum seconds to wait for response (1-300, default: 30)

   • Follow Redirects: Whether to automatically follow HTTP redirects

   • Maximum Retries: Number of retry attempts for failed requests (0-10)

Output Ports

1. response_body (any): Full response body

   • Automatically parsed according to content type

   • JSON responses are converted to objects/arrays

   • XML and text responses are returned as strings

   • Binary responses are base64-encoded

2. status_code (int): HTTP response status code

3. response_headers (object): All response headers as key-value pairs

4. error (string, optional): Error message if request failed

5. Custom outputs (based on response mappings):

   • Additional outputs generated from response mapping rules

   • Types vary based on extracted content

Best Practices

1. URL Construction

   • Use complete URLs including protocol (https://)

   • Consider URL encoding special characters in path segments

   • For dynamic URLs, use variable interpolation rather than string concatenation

2. Authentication Security

   • Store sensitive credentials securely

   • Use OAuth 2.0 when possible for enhanced security

   • Avoid embedding credentials directly in URLs

   • Consider using environment variables for API keys

3. Error Handling

   • Configure reasonable timeout values based on expected response time

   • Set appropriate retry counts for mission-critical requests

   • Use response mapping default values to handle missing data gracefully

   • Check status code before processing response data

4. Response Mapping

   • Use descriptive variable names that indicate content

   • Create focused mappings that extract only needed data

   • Use JSONPath expressions effectively for complex JSON responses

   • Provide sensible default values for optional fields

Common Issues

1. Connection Problems

   • 401/403 Errors: Authentication credentials incorrect or missing

   • Connection Timeout: Target server not responding within timeout period

   • SSL/TLS Errors: Certificate validation issues

2. Request Format Issues

   • 400 Bad Request: Malformed request syntax

   • 415 Unsupported Media Type: Incorrect Content-Type header

   • 413 Payload Too Large: Request body exceeds server limits

   • JSON Parse Errors: Invalid JSON in request body

3. Response Handling

   • Path Expression Errors: Incorrect JSONPath or XPath syntax

   • Missing Fields: Requested fields not present in response

   • Type Mismatches: Expected data type differs from actual response

Examples

Basic GET Request

URL: https://api.example.com/users
Method: GET
Headers:
  - Accept: application/json

Authenticated POST Request with JSON Body

URL: https://api.example.com/data
Method: POST
Headers:
  - Content-Type: application/json
Body Format: JSON
Body Content: {"name": "Example", "value": 42}
Authentication Type: API Key
Auth Configuration:
  - Key Placement: Header
  - Parameter Name: X-API-Key
  - Key: your_api_key_here

Response Mapping Example

Variable Name: user_name
Data Source: Response Body
Path Expression: $.data.user.name
Response Format: JSON
Default Value: "Unknown User"