HttpCurl Class Overview

The HttpCurl class is a curl-compatible HTTP execution engine with built-in dependency resolution. It allows applications to execute curl commands directly, while automatically obtaining prerequisite values required by the request.

At its simplest, HttpCurl can execute a single curl command and provide access to the HTTP response. However, its primary purpose is to automate multi-step workflows where one HTTP request depends on values obtained from earlier requests.

For example, an application may need to:

  1. Authenticate and obtain an access token.
  2. Query an API to locate a resource ID.
  3. Use the resource ID in a final request.

Rather than manually performing each step, the HttpCurl class can determine the required sequence of requests and execute them automatically.

Dependency Resolution

Variables are represented using double braces:

{{access_token}}
{{site_id}}
{{drive_id}}

Variables can appear anywhere within a curl command, including:

  • URL paths
  • Query parameters
  • Request headers
  • Request bodies

When a curl command contains undefined variables, HttpCurl constructs an execution plan based on previously defined curl functions and output mappings. It then executes the necessary requests to obtain the missing values before executing the target request.

For example:

curl https://graph.microsoft.com/v1.0/drives/{{drive_id}}/items

If drive_id is not yet known, HttpCurl can automatically execute one or more dependency functions to determine its value.

Defining Functions

Dependency functions are added using AddFunction.

Each function contains a curl command that can produce one or more output variables. Outputs are defined using AddOutput or AddOutput2, which specify how values are extracted from JSON responses.

For example:

httpCurl.AddFunction(
    "GetDrive",
    "curl https://api.example.com/drives");

httpCurl.AddOutput(
    "GetDrive",
    "id",
    "drive_id");

When drive_id is required by another request, HttpCurl knows that it can execute GetDrive to obtain the value.

Target Outputs

The final target request can also produce variables.

Target outputs are defined using AddTargetOutput, allowing values returned by one request to be automatically stored and reused by future requests.

This makes it possible to build long-running workflows where information discovered by one request becomes available to subsequent requests.

Variable Management

Variables may be:

  • Explicitly assigned using SetVar
  • Automatically extracted from dependency functions
  • Automatically extracted from target responses

Variables remain defined until cleared using ClearVar.

This allows previously discovered values to be reused without repeating unnecessary HTTP requests.

Execution Planning

The DoYourThing method executes a target curl command.

Before execution, HttpCurl examines the command and determines which variables are already known and which must be resolved. It then builds an execution plan that satisfies all dependencies and executes each step in the required order.

The ExaminePlan method can be used to inspect the generated plan without executing it, making it useful for debugging and development.

Authorization

Authorization settings can be configured globally using SetAuth.

The authorization configuration is automatically applied to all HTTP requests executed by the HttpCurl instance, including dependency-resolution requests and target requests.

Response Handling

After execution, the response is available through:

  • ResponseBodyStr
  • GetResponseBd
  • GetResponseSb
  • GetResponseJson
  • GetResponseXml
  • GetResponseJarr

Large responses can be streamed directly to a file by setting ResponseFilePath.

Debugging Support

Several features are available to assist with troubleshooting:

  • ExaminePlan shows the dependency-resolution plan.
  • ToRawRequest converts a curl command into the raw HTTP request that would be sent.
  • FailedCurl identifies the curl command that failed.
  • FailReason provides a categorized failure code.
  • LastErrorText contains detailed diagnostic information.

Typical Use Cases

The HttpCurl class is particularly useful for:

  • REST API automation
  • OAuth and token-based authentication workflows
  • Microsoft Graph and SharePoint operations
  • Cloud service APIs with multiple dependency steps
  • Resource discovery and lookup workflows
  • Complex HTTP integrations where later requests depend on data returned by earlier requests

By combining curl compatibility with automatic dependency resolution, HttpCurl enables complex HTTP workflows to be expressed as a set of interconnected curl commands while allowing the library to determine and execute the required sequence of requests.