3 posts tagged with "api-design"

Rust does not have a shortage of good crates.

There is uuid for identifiers, chrono for time, rust_decimal for exact decimal arithmetic, serde_json for JSON, and reqwest for HTTP. The challenge in application development is often not finding a capability. It is keeping a team fluent in many unrelated APIs while preventing infrastructure details from spreading through business code.

AI coding makes that problem more visible. A model may understand the operation we want while mixing together method names from another language, another version, or another crate. The generated code looks plausible, but the API does not exist.

TeaQL Tool is our attempt to make that surface smaller and more predictable. It places 52 common utilities behind one T::xxx() facade, separates lightweight and dependency-heavy features, and adds an optional context layer that requires code to state why a value is being read, calculated, or changed.

It is partly inspired by libraries such as Hutool, but the interesting question is not how many helpers we can collect. It is whether a stable, narrow API can serve both application developers and coding agents without hiding Rust's underlying ecosystem.

One of the smallest code generator shortcuts creates one of the most persistent API defects:

plural = name + "s"

It works for order, which makes it look harmless. Then it produces order_statuss, categorys, persons, childs, and inventorys.

During TeaQL's six-language acceptance work, we found this assumption in Python and Go query templates and in a Rust diagnostic. The generated code compiled often enough for the mistake to survive until an entity ending in status exposed it.

A generated TeaQL query has exactly one caller-supplied runtime dependency argument: UserContext.

await request.execute_for_list(ctx)

There is no second data-service, provider or connection argument. Those dependencies—together with tenant identity, authenticated user, permissions and policy—are installed when the trusted context is initialized and resolved from it during execution.