Sandman Lua API

Complete reference for all Lua functions available in Sandman. These functions provide HTTP client/server capabilities, data encoding/decoding, and utility functions for your scripts.

Sandman Lua API Overview

Sandman provides a comprehensive Lua API for HTTP scripting, data manipulation, and server creation. The API is organized into several modules, each focused on specific functionality.

API Modules

Global Functions

Core functions available globally without any module prefix:

• print() - Prints values to the console/logs

HTTP Client

Make HTTP requests to external services:

• get() - Makes an HTTP GET request
• post() - Makes an HTTP POST request
• put() - Makes an HTTP PUT request
• delete() - Makes an HTTP DELETE request
• patch() - Makes an HTTP PATCH request
• head() - Makes an HTTP HEAD request
• request() - Sends an HTTP request with custom configuration

HTTP Server

Create HTTP server endpoints and handle requests:

• start() - Starts the HTTP server
• get() - Handles HTTP GET requests on the server
• post() - Handles HTTP POST requests on the server
• put() - Handles HTTP PUT requests on the server
• delete() - Handles HTTP DELETE requests on the server
• patch() - Handles HTTP PATCH requests on the server
• head() - Handles HTTP HEAD requests on the server
• add_route() - Adds a route to the HTTP server

Document Context

Manage document-scoped persistent data:

• set() - Sets a value in the document context
• get() - Gets a value from the document context

JSON Utilities

Encode and decode JSON data:

• sandman.json.try_decode() - Decodes a JSON string into a Lua variable
• encode() - Encodes a Lua variable into a JSON string

Base64 Utilities

Base64 encoding and decoding with URL-safe variants:

• sandman.base64.try_decode() - Decodes a base64 string
• encode() - Encodes a string to base64
• sandman.base64.try_decode_url() - Decodes a URL-safe base64 string
• encode_url() - Encodes a string to URL-safe base64

JWT Utilities

JSON Web Token creation and verification:

• sign() - Signs a JWT token
• sandman.jwt.try_decode() - Decodes a JWT token
• sandman.jwt.try_verify() - Verifies a JWT token

URI Utilities

Parse, construct, and manipulate URIs and URLs:

• parse() - Parses a URI string into components
• tostring() - Converts URI components to a string
• encode() - URI-encodes a url
• decode() - URI-decodes a URI
• encode_component() - URI-encodes a URI component
• decode_component() - URI-decodes a URI component

Quick Start Example

Here’s a simple example that demonstrates several API modules:

-- Start an HTTP server
sandman.server.start({port = 8080})

-- Create a simple API endpoint
sandman.server.get("/api/hello", function(req)
    local response_data = {
        message = "Hello, World!",
        timestamp = os.time(),
        user_agent = req.headers["user-agent"]
    }

    return {
        status = 200,
        headers = {["Content-Type"] = "application/json"},
        body = sandman.json.encode(response_data)
    }
end)

-- Make an HTTP request to external API
local response = sandman.http.get("https://api.github.com/users/octocat")
if response.status == 200 then
    local user_data = sandman.json.decode(response.body)
    print("GitHub user:", user_data.login)

    -- Store in document context
    sandman.document.set("github_user", user_data)
end

Error Handling

Many API functions have “try” variants that return success/failure status instead of throwing errors:

-- Safe JSON decoding
local success, result = sandman.json.try_decode(untrusted_json)
if success then
    print("Parsed JSON:", result)
else
    print("JSON error:", result)
end

-- Safe JWT verification
local valid, payload = sandman.jwt.try_verify(token, secret)
if valid then
    print("User ID:", payload.user_id)
else
    print("Invalid token:", payload)
end

Browse the individual module pages for detailed documentation, examples, and use cases.