API Design on Nalar

Borrowed or Owned Data in Rust API Design

Tue, 01 Sep 2026 00:00:00 +0700

Rust APIs frequently face a design choice that is more important than syntax: should a function borrow data from the caller or take ownership of it?

Borrowing can avoid allocation and make reuse cheap. Ownership can simplify storage and decouple lifetimes. Good APIs use each where it matches the actual data flow.

Borrow when work is temporary

If a function only reads a string during the call, accepting &str is usually natural:

Choosing &str, String, and Cow for Rust Text APIs

Tue, 01 Sep 2026 00:00:00 +0700

Rust has several common ways to represent UTF-8 text, and choosing between &str, String, and Cow<'a, str> is fundamentally an ownership decision.

The best API is usually the one that asks callers for the least ownership it needs and returns ownership only when the result requires it.

Use `&str` when you only need to read text

A string slice borrows UTF-8 text owned elsewhere:

$el.innerText = 'Copy', 2000)" class="absolute top-2 right-2 bg-neutral-700 text-white text-xs px-2 py-1 rounded opacity-0 group-hover:opacity-100 transition-opacity" > Copy

fn is_blank(value: &str) -> bool {
    value.trim().is_empty()
}

This accepts borrowed views into a String, string literals, and other string slices without taking ownership or allocating.

Evolving APIs Without Breaking Clients

Tue, 01 Sep 2026 00:00:00 +0700

An API is not only an HTTP path or function signature. It is a contract about syntax, semantics, timing, errors, ordering, defaults, and lifecycle.

Breaking changes often happen because a server remains syntactically compatible while changing one of those less-visible assumptions.

Safe API evolution starts by identifying what clients can reasonably depend on and designing changes that allow old and new versions to coexist.

Compatibility has multiple dimensions

A change can preserve JSON shape and still break clients.

Use Python Protocols for Structural Typing at API Boundaries

Tue, 01 Sep 2026 00:00:00 +0700

Python often relies on duck typing: if an object supports the operation a function needs, its concrete class does not matter. typing.Protocol gives static type checkers a way to describe that idea explicitly without requiring implementations to inherit from a shared base class.

Define the behavior you consume

$el.innerText = 'Copy', 2000)" class="absolute top-2 right-2 bg-neutral-700 text-white text-xs px-2 py-1 rounded opacity-0 group-hover:opacity-100 transition-opacity" > Copy

from typing import Protocol

class ByteWriter(Protocol):
    def write(self, data: bytes) -> int: ...


def emit_header(writer: ByteWriter) -> None:
    writer.write(b"NLR1")

Any statically compatible object can satisfy ByteWriter, even if its class never mentions the protocol.

Use the Typestate Pattern to Make Invalid Rust States Unrepresentable

Tue, 01 Sep 2026 00:00:00 +0700

Many APIs have lifecycle rules: a connection must be opened before sending, a transaction must begin before committing, or a builder must receive required values before producing output. Runtime flags can enforce these rules, but Rust can sometimes encode them in types instead.

The typestate pattern represents each valid state with a distinct type and makes transitions consume one state to produce another.

Encode states as marker types

$el.innerText = 'Copy', 2000)" class="absolute top-2 right-2 bg-neutral-700 text-white text-xs px-2 py-1 rounded opacity-0 group-hover:opacity-100 transition-opacity" > Copy

use std::marker::PhantomData;

struct Disconnected;
struct Connected;

struct Connection<State> {
    endpoint: String,
    _state: PhantomData<State>,
}

impl Connection<Disconnected> {
    fn new(endpoint: String) -> Self {
        Self { endpoint, _state: PhantomData }
    }

    fn connect(self) -> Connection<Connected> {
        Connection {
            endpoint: self.endpoint,
            _state: PhantomData,
        }
    }
}

impl Connection<Connected> {
    fn send(&self, payload: &[u8]) {
        println!("sending {} bytes", payload.len());
    }
}

send does not exist for Connection<Disconnected>. Incorrect call ordering becomes a compile-time error instead of a branch in production.

API Design on Nalar

Borrowed or Owned Data in Rust API Design

Borrow when work is temporary

Choosing &str, String, and Cow for Rust Text APIs

Use &str when you only need to read text

Evolving APIs Without Breaking Clients

Compatibility has multiple dimensions

Use Python Protocols for Structural Typing at API Boundaries

Define the behavior you consume

Use the Typestate Pattern to Make Invalid Rust States Unrepresentable

Encode states as marker types

Use `&str` when you only need to read text