REST API Processor

The REST API Processor is a component of the EigenLayer-AVS Task Engine that enables tasks to make HTTP requests to external REST APIs.

The REST API Processor is a component of the EigenLayer-AVS Task Engine that enables tasks to make HTTP requests to external REST APIs. This processor supports various HTTP methods, request body formats, header customization, and variable interpolation. It serves as the primary mechanism for tasks to interact with external web services and APIs.

For information about other processors in the Task Engine, see Task Engine and Virtual Machine.

Overview#

The REST API Processor executes HTTP requests defined as RestAPINode objects within task graphs. It supports standard HTTP methods (GET, POST, DELETE), custom headers, request body customization, and dynamic variable interpolation.

Sources:

Implementation#

The REST API Processor is implemented as a RestProcessor struct that extends the CommonProcessor. It uses the go-resty/resty library for making HTTP requests with a configurable timeout (set to 1 minute by default).

Sources:

Request Configuration#

A REST API request is configured through a RestAPINode protobuf object with the following properties:

PropertyTypeDescription
UrlstringThe target URL for the HTTP request
MethodstringHTTP method (GET, POST, DELETE)
Headersmap[string]stringHTTP headers to include in the request
BodystringThe request body (for POST requests)

The processor supports the following HTTP methods:

  • GET: Used for retrieving data from an API
  • POST: Used for creating or updating data
  • DELETE: Used for deleting data

If an unsupported method is specified, the processor defaults to using GET.

Sources:

Template Processing#

The REST API Processor supports template variable interpolation in URLs, headers, and request bodies. This allows dynamic values to be injected based on previous steps in the task execution or trigger data.

Template variables use the syntax {{variableName}}. The processor searches for this pattern in the URL, headers, and body, and replaces these placeholders with corresponding values from the VM's variable context.

For example:

  • URL with template: https://api.example.com/users/{{userId}}
  • Header with template: Authorization: Bearer {{authToken}}
  • Body with template: {"name": "{{userName}}", "email": "{{userEmail}}"}

The processor creates a copy of the original node to avoid modifying the original data structure during template processing.

Sources:

Request Execution#

The request execution process follows these steps:

  1. Initialize an Execution_Step structure to track execution details
  2. Create a copy of the RestAPINode for template processing
  3. Process templates in URL, headers, and body
  4. Set up the HTTP request with the processed values
  5. Execute the appropriate HTTP method
  6. Process the response (parse JSON if applicable)
  7. Store the result in the VM's variable context
  8. Return the execution status and results

Sources:

Response Processing#

The processor handles HTTP responses in the following ways:

  1. For JSON responses (starting with { or <FileRef file-url="https://github.com/AvaProtocol/EigenLayer-AVS/blob/63bc1de4/), it attempts to parse the response into a map structure\n2. If parsing succeeds, the map is stored as the output variable for the step\n3. If parsing fails or the response is not JSON, the raw string is stored instead\n4. The result is also stored in the OutputData field of the Execution_Step\n\nThis automatic JSON parsing simplifies access to structured data in subsequent task steps.\n\nSources#LNaN-LNaN" NaN file-path="), it attempts to parse the response into a map structure\n2. If parsing succeeds, the map is stored as the output variable for the step\n3. If parsing fails or the response is not JSON, the raw string is stored instead\n4. The result is also stored in the OutputDatafield of theExecution_Step`\n\nThis automatic JSON parsing simplifies access to structured data in subsequent task steps.\n\nSources">Hii

Error Handling#

The REST API Processor implements comprehensive error handling:

  1. URL parsing errors are captured and reported

  2. Connection failures (status code 0) are reported as connection errors or timeouts

  3. HTTP status codes outside the 2xx-3xx range are considered errors:

    • 4xx errors indicate client errors (e.g., 404 Not Found)
    • 5xx errors indicate server errors

When an error occurs:

  1. The Success field in Execution_Step is set to false
  2. The error message is stored in the Error field
  3. The error is also returned from the Execute method

For 404 errors specifically, the processor logs additional diagnostic information to help troubleshoot the issue.

Sources:

Logging and Debugging#

The processor includes comprehensive logging capabilities:

  1. Request details (method, URL, headers, body) are logged at debug level
  2. Available variables for template rendering are logged to assist with debugging
  3. Response details (status code, headers, body) are logged
  4. For large responses, the body is truncated to 1000 characters in logs

These logs help with troubleshooting issues when making HTTP requests.

Sources:

Usage Examples#

Here's a simplified example of a task that uses the REST API Processor:

- TaskNode:
  - Id: "fetch_user_data"
  - Name: "Get User Profile"
  - TaskType: RestApi
    - Url: "https://api.example.com/users/{{userId}}"
    - Method: "GET"
    - Headers:
      - "Authorization": "Bearer {{authToken}}"
      - "Content-Type": "application/json"

After execution, the user data (parsed from JSON) would be available in subsequent steps as {{fetch_user_data.data}}.

For POST requests with dynamic data:

- TaskNode:
  - Id: "create_user"
  - Name: "Create User"
  - TaskType: RestApi
    - Url: "https://api.example.com/users"
    - Method: "POST"
    - Headers:
      - "Authorization": "Bearer {{authToken}}"
      - "Content-Type": "application/json"
    - Body: '{"name": "{{userName}}", "email": "{{userEmail}}"}'

Sources:

Integration with Task Engine#

Within the EigenLayer-AVS system, the REST API Processor is one of several task node processors managed by the Virtual Machine component of the Task Engine. The VM creates and initializes the REST Processor when needed to execute REST API nodes within a task graph.

The REST API Processor receives data from previous task steps through the VM's variable context, which enables complex workflows that combine multiple API calls and other processing steps.

Sources:

Feature this wiki to auto refresh weekly