wren/manual_src/pages/api/http.html

{# retoor <retoor@molodetz.nl> #}
{% extends 'page.html' %}

{% set page_title = "http" %}
{% set breadcrumb = [{"url": "api/index.html", "title": "API Reference"}, {"title": "http"}] %}
{% set prev_page = {"url": "api/index.html", "title": "API Overview"} %}
{% set next_page = {"url": "api/websocket.html", "title": "websocket"} %}

{% block article %}
                <h1>http</h1>

                <p>The <code>http</code> module provides an HTTP client for making requests to web servers. It supports both HTTP and HTTPS, all common HTTP methods, custom headers, and JSON handling.</p>

                <pre><code>import "http" for Http, HttpResponse, Url</code></pre>

                <div class="toc">
                    <h4>On This Page</h4>
                    <ul>
                        <li><a href="#http-class">Http Class</a></li>
                        <li><a href="#httpresponse-class">HttpResponse Class</a></li>
                        <li><a href="#url-class">Url Class</a></li>
                        <li><a href="#examples">Examples</a></li>
                    </ul>
                </div>

                <h2 id="http-class">Http Class</h2>
                <p>The main class for making HTTP requests. All methods are static.</p>

                <div class="class-header">
                    <h3>Http</h3>
                    <p>Static class for making HTTP requests</p>
                </div>

                <h3>Static Methods</h3>

                <div class="method-signature">
                    <span class="method-name">Http.get</span>(<span class="param">url</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs an HTTP GET request.</p>
                <ul class="param-list">
                    <li><span class="param-name">url</span> <span class="param-type">(String)</span> - The URL to request</li>
                    <li><span class="returns">Returns:</span> HttpResponse object</li>
                </ul>
                <pre><code>var response = Http.get("https://api.example.com/users")
System.print(response.body)</code></pre>

                <div class="method-signature">
                    <span class="method-name">Http.get</span>(<span class="param">url</span>, <span class="param">headers</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs an HTTP GET request with custom headers.</p>
                <ul class="param-list">
                    <li><span class="param-name">url</span> <span class="param-type">(String)</span> - The URL to request</li>
                    <li><span class="param-name">headers</span> <span class="param-type">(Map)</span> - Custom headers to include</li>
                    <li><span class="returns">Returns:</span> HttpResponse object</li>
                </ul>
                <pre><code>var headers = {"Authorization": "Bearer token123"}
var response = Http.get("https://api.example.com/me", headers)</code></pre>

                <div class="method-signature">
                    <span class="method-name">Http.post</span>(<span class="param">url</span>, <span class="param">body</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs an HTTP POST request with a body.</p>
                <ul class="param-list">
                    <li><span class="param-name">url</span> <span class="param-type">(String)</span> - The URL to post to</li>
                    <li><span class="param-name">body</span> <span class="param-type">(String|Map|List)</span> - Request body. Maps and Lists are JSON-encoded automatically.</li>
                    <li><span class="returns">Returns:</span> HttpResponse object</li>
                </ul>
                <pre><code>var data = {"name": "Alice", "email": "alice@example.com"}
var response = Http.post("https://api.example.com/users", data)</code></pre>

                <div class="method-signature">
                    <span class="method-name">Http.post</span>(<span class="param">url</span>, <span class="param">body</span>, <span class="param">headers</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs an HTTP POST request with a body and custom headers.</p>
                <ul class="param-list">
                    <li><span class="param-name">url</span> <span class="param-type">(String)</span> - The URL to post to</li>
                    <li><span class="param-name">body</span> <span class="param-type">(String|Map|List)</span> - Request body</li>
                    <li><span class="param-name">headers</span> <span class="param-type">(Map)</span> - Custom headers</li>
                    <li><span class="returns">Returns:</span> HttpResponse object</li>
                </ul>

                <div class="method-signature">
                    <span class="method-name">Http.put</span>(<span class="param">url</span>, <span class="param">body</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs an HTTP PUT request.</p>

                <div class="method-signature">
                    <span class="method-name">Http.put</span>(<span class="param">url</span>, <span class="param">body</span>, <span class="param">headers</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs an HTTP PUT request with custom headers.</p>

                <div class="method-signature">
                    <span class="method-name">Http.delete</span>(<span class="param">url</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs an HTTP DELETE request.</p>

                <div class="method-signature">
                    <span class="method-name">Http.delete</span>(<span class="param">url</span>, <span class="param">headers</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs an HTTP DELETE request with custom headers.</p>

                <div class="method-signature">
                    <span class="method-name">Http.patch</span>(<span class="param">url</span>, <span class="param">body</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs an HTTP PATCH request.</p>

                <div class="method-signature">
                    <span class="method-name">Http.patch</span>(<span class="param">url</span>, <span class="param">body</span>, <span class="param">headers</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs an HTTP PATCH request with custom headers.</p>

                <div class="method-signature">
                    <span class="method-name">Http.request</span>(<span class="param">url</span>, <span class="param">method</span>, <span class="param">body</span>, <span class="param">headers</span>) → <span class="type">HttpResponse</span>
                </div>
                <p>Performs a custom HTTP request with full control over method, body, and headers.</p>
                <ul class="param-list">
                    <li><span class="param-name">url</span> <span class="param-type">(String)</span> - The URL to request</li>
                    <li><span class="param-name">method</span> <span class="param-type">(String)</span> - HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)</li>
                    <li><span class="param-name">body</span> <span class="param-type">(String|Map|List|null)</span> - Request body or null</li>
                    <li><span class="param-name">headers</span> <span class="param-type">(Map)</span> - Custom headers</li>
                    <li><span class="returns">Returns:</span> HttpResponse object</li>
                </ul>
                <pre><code>var response = Http.request(
    "https://api.example.com/users/1",
    "OPTIONS",
    null,
    {}
)</code></pre>

                <h2 id="httpresponse-class">HttpResponse Class</h2>
                <p>Represents an HTTP response returned from a request.</p>

                <div class="class-header">
                    <h3>HttpResponse</h3>
                    <p>HTTP response object with status, headers, and body</p>
                </div>

                <h3>Properties</h3>

                <div class="method-signature">
                    <span class="method-name">statusCode</span> → <span class="type">Num</span>
                </div>
                <p>The HTTP status code (e.g., 200, 404, 500).</p>

                <div class="method-signature">
                    <span class="method-name">statusText</span> → <span class="type">String</span>
                </div>
                <p>The HTTP status text (e.g., "OK", "Not Found").</p>

                <div class="method-signature">
                    <span class="method-name">headers</span> → <span class="type">Map</span>
                </div>
                <p>A map of response headers (header name to value).</p>

                <div class="method-signature">
                    <span class="method-name">body</span> → <span class="type">String</span>
                </div>
                <p>The response body as a string.</p>

                <div class="method-signature">
                    <span class="method-name">ok</span> → <span class="type">Bool</span>
                </div>
                <p>True if the status code is in the 200-299 range.</p>

                <h3>Methods</h3>

                <div class="method-signature">
                    <span class="method-name">header</span>(<span class="param">name</span>) → <span class="type">String|null</span>
                </div>
                <p>Gets a header value by name (case-insensitive).</p>
                <ul class="param-list">
                    <li><span class="param-name">name</span> <span class="param-type">(String)</span> - Header name</li>
                    <li><span class="returns">Returns:</span> Header value or null if not found</li>
                </ul>
                <pre><code>var contentType = response.header("Content-Type")</code></pre>

                <div class="method-signature">
                    <span class="method-name">json</span> → <span class="type">Map|List|null</span>
                </div>
                <p>Parses the response body as JSON and returns the result.</p>
                <pre><code>var data = response.json
System.print(data["name"])</code></pre>

                <h2 id="url-class">Url Class</h2>
                <p>Utility class for parsing URLs into their components.</p>

                <div class="class-header">
                    <h3>Url</h3>
                    <p>URL parser</p>
                </div>

                <h3>Constructor</h3>

                <div class="method-signature">
                    <span class="method-name">Url.parse</span>(<span class="param">url</span>) → <span class="type">Url</span>
                </div>
                <p>Parses a URL string into its components.</p>
                <pre><code>var url = Url.parse("https://example.com:8080/path?query=value")
System.print(url.scheme)  // https
System.print(url.host)    // example.com
System.print(url.port)    // 8080
System.print(url.path)    // /path
System.print(url.query)   // query=value</code></pre>

                <h3>Properties</h3>

                <table>
                    <tr>
                        <th>Property</th>
                        <th>Type</th>
                        <th>Description</th>
                    </tr>
                    <tr>
                        <td><code>scheme</code></td>
                        <td>String</td>
                        <td>URL scheme (http, https)</td>
                    </tr>
                    <tr>
                        <td><code>host</code></td>
                        <td>String</td>
                        <td>Hostname</td>
                    </tr>
                    <tr>
                        <td><code>port</code></td>
                        <td>Num</td>
                        <td>Port number (80 for http, 443 for https by default)</td>
                    </tr>
                    <tr>
                        <td><code>path</code></td>
                        <td>String</td>
                        <td>URL path</td>
                    </tr>
                    <tr>
                        <td><code>query</code></td>
                        <td>String</td>
                        <td>Query string (without leading ?)</td>
                    </tr>
                    <tr>
                        <td><code>fullPath</code></td>
                        <td>String</td>
                        <td>Path with query string</td>
                    </tr>
                </table>

                <h2 id="examples">Examples</h2>

                <h3>Simple GET Request</h3>
                <pre><code>import "http" for Http

var response = Http.get("https://httpbin.org/get")
System.print("Status: %(response.statusCode)")
System.print("Body: %(response.body)")</code></pre>

                <h3>POST with JSON Body</h3>
                <pre><code>import "http" for Http

var data = {
    "username": "alice",
    "email": "alice@example.com"
}

var response = Http.post("https://httpbin.org/post", data)

if (response.ok) {
    System.print("User created!")
    System.print(response.json)
} else {
    System.print("Error: %(response.statusCode)")
}</code></pre>

                <h3>Custom Headers with Authentication</h3>
                <pre><code>import "http" for Http

var headers = {
    "Authorization": "Bearer eyJhbGciOiJIUzI1NiIs...",
    "Accept": "application/json"
}

var response = Http.get("https://api.example.com/me", headers)
var user = response.json
System.print("Hello, %(user["name"])!")</code></pre>

                <h3>Error Handling</h3>
                <pre><code>import "http" for Http

var fiber = Fiber.new {
    var response = Http.get("https://invalid-domain.example")
    return response
}

var result = fiber.try()
if (fiber.error) {
    System.print("Request failed: %(fiber.error)")
} else {
    System.print("Got response: %(result.statusCode)")
}</code></pre>

                <h3>Sending Form Data</h3>
                <pre><code>import "http" for Http

var formData = "username=alice&password=secret"
var headers = {
    "Content-Type": "application/x-www-form-urlencoded"
}

var response = Http.post("https://example.com/login", formData, headers)</code></pre>

                <h3>Checking Response Headers</h3>
                <pre><code>import "http" for Http

var response = Http.get("https://example.com")

System.print("Content-Type: %(response.header("Content-Type"))")
System.print("Server: %(response.header("Server"))")

for (entry in response.headers) {
    System.print("%(entry.key): %(entry.value)")
}</code></pre>

                <div class="admonition note">
                    <div class="admonition-title">Note</div>
                    <p>The HTTP module automatically handles HTTPS by using the TLS module. No additional configuration is needed for HTTPS URLs.</p>
                </div>

                <div class="admonition tip">
                    <div class="admonition-title">Tip</div>
                    <p>When posting a Map or List, the module automatically sets <code>Content-Type: application/json</code> and JSON-encodes the body. For other content types, pass a string body and set the Content-Type header explicitly.</p>
                </div>
{% endblock %}