HTTP Requests

Sometimes connected prototypes need external data from web APIs—such as real-time weather reports, currency exchange rates, AI endpoints, or webhooks that trigger alerts in Slack or Microsoft Teams. Rather than managing complex HTTPS client libraries or certificates on low-power microcontrollers, you can delegate outbound web requests to the http-web-request service built into the OOCSI server.

The `http-web-request` Service

sequenceDiagram
    autonumber
    actor Client as OOCSI Client (ESP32 / Python / JS)
    participant Broker as OOCSI Broker
    participant Service as http-web-request Service
    actor External as External Web API (Weather, Slack, AI)

    Note over Client,Broker: 1. Request outbound HTTP call
    Client->>Broker: send("http-web-request", {url: "...", method: "get"})
    Broker->>Service: Forward request message

    Note over Service,External: 2. Server executes HTTP/HTTPS request
    Service->>External: GET /v1/current.json
    External-->>Service: 200 OK (JSON payload)

    Note over Service,Client: 3. Deliver response back to client
    Service->>Broker: send("client_####", {status: 200, body: "..."})
    Broker->>Client: Deliver response event

The OOCSI server runs a background client named http-web-request. Any connected client can send a message to http-web-request specifying the target URL, HTTP method, and payload. The server executes the request asynchronously and returns the response event to the calling client (or routes it to a designated channel).

Sending HTTP Requests

1. GET Requests

To fetch data from a public API, send a message with url and method: "get":

In Python

oocsi.send('http-web-request', {
    'url': 'https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q=Amsterdam',
    'method': 'get'
})

In JavaScript (oocsi-web.js)

OOCSI.send("http-web-request", {
    url: "https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q=Amsterdam",
    method: "get"
});

In Java / Processing

oocsi.channel("http-web-request")
    .data("url", "https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q=Amsterdam")
    .data("method", "get")
    .submit();

2. POST Requests (JSON & Form Encoded)

To post data to a remote webhook or REST API:

Sending JSON Payloads

Specify method: "post" and supply the payload string in json:

# Python
oocsi.send('http-web-request', {
    'url': 'https://httpbin.org/post',
    'method': 'post',
    'json': '{"temperature": 21.5, "status": "active"}'
})

// JavaScript
OOCSI.send("http-web-request", {
    url: "https://httpbin.org/post",
    method: "post",
    json: JSON.stringify({ temperature: 21.5, status: "active" })
});

Sending Form URL-Encoded Data

Supply the encoded string in body:

oocsi.send('http-web-request', {
    'url': 'https://example.org/api/trigger',
    'method': 'post',
    'body': 'action=notify&level=warning'
})

Receiving the Response

By default, the http-web-request service sends the response message directly back to the client that requested it.

Response Payload Structure

The response message event contains the following keys:

status: The HTTP status code as an integer (e.g. 200, 404, 500).
body: The raw text or JSON response returned by the remote server.
error: Optional error message if the network request failed or timed out.

# In Python: listen for direct response from http-web-request
@oocsi.event()
def handle_response(sender, recipient, data):
    if sender == 'http-web-request':
        status = data.get('status')
        body = data.get('body')
        print(f"HTTP Status: {status}")
        print(f"Response Body: {body}")

// In JavaScript: listen for direct messages
OOCSI.subscribe(myClientName, function(msg) {
    if (msg.sender === "http-web-request") {
        console.log("HTTP Status:", msg.data.status);
        console.log("Body:", msg.data.body);
    }
});

Routing Responses to a Shared Channel

If multiple clients need to consume the API response (e.g., broadcasting fresh weather data to all smart displays in a team space), specify the channel attribute in the request:

oocsi.send('http-web-request', {
    'url': 'https://api.weatherapi.com/v1/current.json?key=YOUR_KEY&q=Amsterdam',
    'method': 'get',
    'channel': 'weather_broadcast'
})

The OOCSI server will fetch the URL and broadcast the resulting {status, body} directly to the weather_broadcast channel for all subscribers to receive simultaneously.

Security Restrictions

To protect the host server from Server-Side Request Forgery (SSRF) and local network enumeration:

Blocked Schemes: Only http:// and https:// requests are allowed. Local file schemes (file://), FTP (ftp://), and Gopher are blocked.
Blocked IP Ranges: Requests targeting loopback addresses (127.0.0.1, localhost), private RFC 1918 subnets (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16), and cloud metadata endpoints (169.254.169.254) are rejected on secured server instances.