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