# 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"
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.waterflai.ai/studio/studio-builders/flow-components-nodes/api-request-node.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.