API Design and Semver

Start with the idea

Newtypes stop two u64s being swapped, typestate stops a request being sent twice, and returning Result instead of panicking hands the decision to the caller. Semver then constrains what you may change: adding a public enum variant or a trait method is a breaking change, which is why non_exhaustive and sealed traits exist.

A good API makes common correct use easy and misuse visible. A UserId newtype prevents an OrderId from being passed accidentally, even if both contain u64. A function returning Result lets callers decide how to handle expected failure instead of panicking. Ownership in signatures tells callers whether data is borrowed, mutated, or consumed. These design choices are especially important at public crate boundaries because users rely on them longer than internal helpers do.