Quick Reference

A comprehensive reference for all mik-sdk APIs.

Required Imports

Every handler file needs these imports:

#[allow(warnings)]
mod bindings;

use bindings::exports::mik::core::handler::{self, Guest, Response};
use mik_sdk::prelude::*;

• bindings - Generated by cargo-component from your WIT files
• Guest - The trait your handler implements (generated by the routes! macro)
• Response - The response type returned by handlers
• mik_sdk::prelude::* - All SDK types and macros

Modules

The prelude includes all common modules:

Module	Purpose
json	JSON building and parsing
time	UTC timestamps and ISO 8601
random	UUIDs, tokens, random bytes
log	Structured logging to stderr
env	Environment variable access
http_client	Outbound HTTP requests
status	HTTP status code constants
query	Cursor, PageInfo, Value (with sql feature)

Types

Type	Purpose
Request	HTTP request wrapper
Method	HTTP method enum
Id	Built-in single path parameter
ParseError	JSON/input parsing errors
ValidationError	Field validation errors

Derive Macros

Macro	Purpose
#[derive(Type)]	JSON body/response with OpenAPI schema
#[derive(Query)]	Query string parameters with defaults
#[derive(Path)]	URL path parameters

Field Attributes

#[derive(Type)]
pub struct Example {
    #[field(min = 1, max = 100)]
    pub name: String,

    #[field(format = "email")]
    pub email: String,

    #[field(rename = "userName")]
    pub user_name: String,

    #[field(docs = "Description for OpenAPI")]
    pub field: String,
}

#[derive(Query)]
pub struct QueryExample {
    #[field(default = 1)]
    pub page: u32,

    #[field(default = 20, max = 100)]
    pub limit: u32,
}

Enums

Use #[derive(Type)] on enums to serialize them as JSON strings. Only unit variants (no fields) are supported.

#[derive(Type)]
pub enum Status {
    Active,     // serializes as "active"
    Inactive,   // serializes as "inactive"
    Pending,    // serializes as "pending"
}

#[derive(Type)]
pub enum Priority {
    #[field(rename = "HIGH")]
    High,
    #[field(rename = "MEDIUM")]
    Medium,
    #[field(rename = "LOW")]
    Low,
}

Behavior:

• Variants are converted from PascalCase to snake_case by default (SuperAdmin → "super_admin")
• Use #[field(rename = "...")] on variants to customize the JSON string
• Invalid values return a helpful error listing all valid options
• OpenAPI schema is generated as { "type": "string", "enum": ["active", "inactive", "pending"] }

Usage in structs:

#[derive(Type)]
pub struct Task {
    pub id: String,
    pub status: Status,
    pub priority: Priority,
}

Response Macros

Macro	Status	Purpose
ok!({ ... })	200	JSON response
created!(location, { ... })	201	Created with Location
accepted!()	202	Accepted
no_content!()	204	No Content
redirect!(url)	302	Redirect
bad_request!(msg)	400	Bad Request
forbidden!(msg)	403	Forbidden
not_found!(msg)	404	Not Found
conflict!(msg)	409	Conflict
error! { ... }	any	RFC 7807 Problem Details

DX Macros

Macro	Purpose
guard!(cond, status, msg)	Early return if false
ensure!(expr, status, msg)	Unwrap or return error
fetch!(METHOD url, ...)	Build HTTP request
routes! { ... }	Define routes
json!({ ... })	Build JSON value

SQL Macros

Macro	Purpose
sql_read!(table { ... })	SELECT query
sql_create!(table { ... })	INSERT query
sql_update!(table { ... })	UPDATE query
sql_delete!(table { ... })	DELETE query
ids!(collection)	Extract IDs for batching

Request Methods

Method	Returns	Description
method()	Method	HTTP method
path()	&str	Full path with query
path_without_query()	&str	Path only
param_or(name, def)	&str	Path parameter
query_or(name, def)	&str	Query parameter
query_all(name)	&[String]	All query values
header_or(name, def)	&str	Header (case-insensitive)
header_all(name)	Vec<&str>	All header values
trace_id_or(def)	&str	traceparent header
bearer_token_or(def)	&str	Bearer token from Auth
body()	Option<&[u8]>	Raw body bytes
text()	Option<&str>	Body as UTF-8
json()	Option<JsonValue>	Parse as JSON
json_with(parser)	Option<T>	Parse with custom parser
has_body()	bool	True if non-empty
content_type_or(def)	&str	Content-Type header
is_json()	bool	Content-Type is JSON
is_form()	bool	Content-Type is form
form_or(name, def)	&str	Form field value
form_all(name)	&[String]	All form values

JSON Module

Building

json::obj()                    // Empty object {}
json::arr()                    // Empty array []
json::str("text")              // String value
json::int(42)                  // Integer value
json::float(3.14)              // Float value
json::bool(true)               // Boolean value
json::null()                   // Null value

// Chaining
json::obj()
    .set("name", json::str("Alice"))
    .set("age", json::int(30))

json::arr()
    .push(json::int(1))
    .push(json::int(2))

Parsing

// From request
let parsed = req.json()?;

// From HTTP response
let parsed = resp.json()?;

// From raw bytes (low-level)
let parsed = json::try_parse(bytes)?;

// Path accessors (lazy - fast)
parsed.path_str(&["user", "name"])     // Option<String>
parsed.path_int(&["user", "age"])      // Option<i64>
parsed.path_float(&["metrics", "score"]) // Option<f64>
parsed.path_bool(&["user", "active"])  // Option<bool>
parsed.path_exists(&["field"])         // bool
parsed.path_is_null(&["field"])        // bool

// With defaults
parsed.path_str_or(&["name"], "Anonymous")
parsed.path_int_or(&["age"], 0)

// Tree access (triggers full parse)
parsed.get("key")             // JsonValue
parsed.at(0)                  // JsonValue (array index)
parsed.keys()                 // Vec<String>
parsed.len()                  // Option<usize>

Time Module

time::now()              // u64 - Unix seconds
time::now_millis()       // u64 - Unix milliseconds
time::now_iso()          // String - ISO 8601

// Convert raw values
time::to_millis(secs, nanos)
time::to_iso(secs, nanos)

Random Module

random::uuid()           // String - UUID v4
random::hex(n)           // String - n bytes as hex
random::bytes(n)         // Vec<u8> - n random bytes
random::u64()            // u64 - random integer

Log Module

// Format-string style
log::info!("User {} logged in", user_id);
log::warn!("Cache miss: {}", key);
log::error!("Failed: {}", err);
log::debug!("Debug: {:?}", data);  // Release: compiled out

// Structured style
log!(info, "user created", id: user_id, email: &email);
log!(warn, "rate limit", remaining: count);
log!(error, "fetch failed", url: &url, status: code);

Environment Module

env::get("KEY")              // Option<String>
env::get_or("KEY", "default") // String
env::require("KEY")          // String (panics if missing)

Status Constants

status::OK                   // 200
status::CREATED              // 201
status::ACCEPTED             // 202
status::NO_CONTENT           // 204
status::MOVED_PERMANENTLY    // 301
status::FOUND                // 302
status::BAD_REQUEST          // 400
status::UNAUTHORIZED         // 401
status::FORBIDDEN            // 403
status::NOT_FOUND            // 404
status::CONFLICT             // 409
status::UNPROCESSABLE_ENTITY // 422
status::TOO_MANY_REQUESTS    // 429
status::INTERNAL_SERVER_ERROR // 500
status::BAD_GATEWAY          // 502
status::SERVICE_UNAVAILABLE  // 503
status::GATEWAY_TIMEOUT      // 504

HTTP Client

// GET request
fetch!(GET "https://api.example.com/data").send()?;

// POST with JSON
fetch!(POST "https://api.example.com/users", json: {
    "name": "Alice"
}).send()?;

// With options
fetch!(GET "https://api.example.com",
    headers: { "Authorization": format!("Bearer {}", token) },
    timeout: 5000
).send()?;

// SSRF protection
fetch!(GET &user_url)
    .deny_private_ips()
    .send()?;

// Trace propagation
let trace_id = req.trace_id_or("");
fetch!(GET "https://api.example.com")
    .with_trace_id(if trace_id.is_empty() { None } else { Some(trace_id) })
    .send()?;

// Response handling
let resp = fetch!(GET "https://api.example.com").send()?;
resp.is_success()   // bool
resp.status()       // u16
resp.body()         // Vec<u8>
resp.header("name") // Option<&str>

SQL Query Builder

// SELECT
sql_read!(users {
    select: [id, name, email],
    filter: { active: true, age: { $gte: 18 } },
    order: [-created_at, name],
    limit: 20,
})

// INSERT
sql_create!(users {
    name: "Alice",
    email: "alice@example.com",
    returning: [id],
})

// UPDATE
sql_update!(users {
    set: { name: "Bob", updated_at: time::now_iso() },
    filter: { id: 123 },
})

// DELETE
sql_delete!(users {
    filter: { id: 123 },
})

// SQLite dialect
sql_read!(sqlite, users { ... })

Filter Operators

Operator	Description
$eq	Equal
$ne	Not equal
$gt	Greater than
$gte	Greater or equal
$lt	Less than
$lte	Less or equal
$in	In list
$nin	Not in list
$like	LIKE pattern
$starts_with	Starts with
$ends_with	Ends with
$contains	Contains
$between	Between range
$and	Logical AND
$or	Logical OR
$not	Logical NOT

Cursor Pagination

use mik_sdk::query::Cursor;

// Encode cursor
let cursor = Cursor::new()
    .string("created_at", &last.created_at)
    .int("id", last.id)
    .encode();

// Use in query
sql_read!(posts {
    order: [-created_at, -id],
    after: Some(&cursor),
    limit: 20,
})