forgeHttp

Invalid *emphasis* [fandoc:67] - ""

# ForgeHttp — HTTP Client Library for SkySpark

ForgeHttp is an HTTP client library for SkySpark, providing Axon functions to make HTTP requests easily, with built-in support for authentication via SkySpark connectors.

---

## What It Supports

* Standard HTTP methods: GET, POST, PUT, DELETE, plus custom methods like PATCH, HEAD, OPTIONS, etc. * Automatic JSON serialization and deserialization. * Download and save binary files to disk. * Connector integration to securely handle credentials (API keys, secrets, passwords). * Supports form-encoded, JSON, XML, plain text bodies. * Debug logging and error handling. * Auto-detection of binary content types.

---

## URL Input Types

ForgeHttp accepts three types of URL inputs:

1. String: "https://api.example.com/data"
2. Uri: Uri.fromStr("https://api.example.com/data")
3. Dict with connector: {uri: "https://api.example.com/data", id: @myConnector}

---

## Using Connectors for Credentials

ForgeHttp can automatically insert credentials stored in connectors.

### What can be stored in a connector?

url — base URL or endpoint apiKey — API key secret — secret key or client secret password — password

### How are they used?

* If you pass a connector dict ({uri: ..., id: ...}) as the first argument instead of a plain URL string, ForgeHttp uses the connector's stored URL automatically. * You can include placeholders like <connApiKey>, <connSecret>, or <connPassword> in request headers or body strings. These will be replaced automatically with the stored values from the connector.

---

## Options Dictionary

The opts parameter accepts a Dict with the following keys:

debug: true - Enable detailed debug logging and return extended response info saveToFile: Str or Uri - Filename to save binary content, or true to auto-extract from Content-Disposition header

---

## Body Handling

### Automatic Content-Type Detection

Dict body → application/json (auto-serialized) Str body → application/x-www-form-urlencoded (if no Content-Type specified)

### Supported Body Types

* **Dict**: Automatically converted to JSON * **Str**: Sent as-is (form-encoded, XML, plain text, etc.) * **null**: No body sent

### Content-Type Override

Set explicit Content-Type in headers to override auto-detection:

`axon headers := {"Content-Type": "application/xml"} body := "<xml>data</xml>" response := forgeHttpPost(url, headers, body) `

---

## Basic Usage Examples

### Simple GET Request

`axon response := forgeHttpGet("https://api.example.com/data")

if (response->status == 200) {

data := response->body.ioReadJson()
echo("Received data: " + data)

} `

### GET Request with Headers and Connector Authentication

`axon headers := {

"Authorization": "Bearer <connApiKey>",
"Accept": "application/json"

}

connUrl := {uri: "https://api.example.com/protected", id: @myConnector} response := forgeHttpGet(connUrl, headers)

if (response->status == 200) {

echo("Authorized data received")

} `

### POST with JSON Body

`axon body := {

name: "Alice",
email: "alice@example.com"

}

response := forgeHttpPost("https://api.example.com/users", null, body)

if (response->status == 201) {

userId := response->body.ioReadJson()->id
echo("User created with ID: " + userId)

} `

### POST Form-Encoded Data

`axon headers := {"Content-Type": "application/x-www-form-urlencoded"} body := "name=Alice&email=alice@example.com"

response := forgeHttpPost("https://api.example.com/form", headers, body) `

---

## Saving Files to Disk

ForgeHttp automatically detects binary content and supports downloading files.

### Binary Content Detection

Binary content is detected by Content-Type headers: * application/pdf, application/zip, application/octet-stream * image/*, video/*, audio/* * application/msword, application/vnd.ms-excel, etc.

### File Saving Options

Specify filename: `axon opts := {saveToFile: "report.pdf"} response := forgeHttpGet("https://api.example.com/reports/latest.pdf", null, null, opts) `

Auto-extract from Content-Disposition header: `axon opts := {saveToFile: true} response := forgeHttpGet("https://api.example.com/download", null, null, opts) `

File save response: `axon if (response->status == 200) {

echo("File saved to: " + response->fileSaved->filePath)
echo("File size: " + response->fileSaved->size + " bytes")
echo("Content type: " + response->fileSaved->contentType)

} `

### File Storage Location

Files are saved to the SkySpark io/ directory. Paths are automatically prefixed with io/ if not specified.

---

## Authentication Examples with Connectors

### API Key in Header

`axon headers := {

"X-API-Key": "<connApiKey>",
"Content-Type": "application/json"

} connUrl := {uri: "https://api.example.com/data", id: @myConnector} response := forgeHttpGet(connUrl, headers) `

### Basic Authentication

`axon username := "<connApiKey>" password := "<connSecret>" credentials := (username + ":" + password).toBuf.toBase64

headers := {"Authorization": "Basic " + credentials} connUrl := {uri: "https://api.example.com/data", id: @myConnector} response := forgeHttpGet(connUrl, headers) `

---

## Debug Mode

Enable debug mode for detailed request/response information:

`axon opts := {debug: true} response := forgeHttpGet("https://api.example.com/data", null, null, opts)

// Debug response includes: // - rawHeaders, reqHeaders, resHeaders // - rawBody, reqBody, response, parsed // - Full request/response details `

---

## Error Handling

### HTTP Status Codes

`axon response := forgeHttpGet("https://api.example.com/data")

if (response->status >= 200 and response->status < 300) {

echo("Success: " + response->body.ioReadJson())

} else if (response->status == 401) {

echo("Authentication failed")

} else if (response->status == 404) {

echo("Resource not found")

} else {

echo("Request error: " + response->statusText)

} `

### Network Errors

Network failures return status 0:

`axon if (response->status == 0) {

echo("Network error: " + response->error)

} `

---

## Advanced Features

### Custom HTTP Methods

`axon response := forgeHttpRequest("PATCH", url, headers, body) response := forgeHttpRequest("HEAD", url, headers) response := forgeHttpRequest("OPTIONS", url, headers) `

### Binary Content Handling

When binary content is detected without saveToFile:

`axon if (response->isBinary == true) {

echo("Binary content detected: " + response->contentType)
echo("Size: " + response->size + " bytes")
echo("Use saveToFile option to download")

} `

### Connector Placeholder Support

Available placeholders in headers and body: * <connApiKey> → connector's apiKey field * <connSecret> → connector's secret field * <connPassword> → connector's password field

---

## Response Format

### Standard Response

`axon {

status: 200,
statusText: "OK",
headers: "{\"Content-Type\":\"application/json\"}",
body: "response content",
url: "https://api.example.com/data",
method: "GET"

} `

### Binary Response (with saveToFile)

`axon {

status: 200,
statusText: "OK",
headers: "{\"Content-Type\":\"application/pdf\"}",
body: "File saved successfully",
url: "https://api.example.com/file.pdf",
method: "GET",
isBinary: true,
contentType: "application/pdf",
fileSaved: {
  success: true,
  filePath: "io/report.pdf",
  fileUrl: "file:///.../io/report.pdf",
  size: 12345,
  contentType: "application/pdf"
}

} `

### Error Response

`axon {

status: 0,
statusText: "Request Failed",
error: "Connection timeout",
url: "https://api.example.com/data",
method: "GET"

} `

---

## Summary

ForgeHttp provides:

Flexible URL input: String, Uri, or Dict with connector integration Automatic content handling: JSON serialization, binary detection, file saving Secure authentication: Connector-based credential management with placeholders Comprehensive options: Debug mode, file saving, custom methods Robust error handling: Network errors, HTTP status codes, detailed responses LLM-friendly: Clear response format, detailed documentation, predictable behavior

---

If you want, I can also prepare a concise cheat-sheet or a set of ready-to-use code snippets based on this. Would that be helpful?