An API is the set of publicly accessible operations and state through which a component helps clients achieve their goals. A well-designed API makes this public surface coincide with observable behavior while hiding implementation details behind a private API. section 5.2 section 5.5
Classify an API along two independent dimensions:
- Public versus private: access modifiers determine what client code can reach. section 5.2
- Observable behavior versus implementation details: observable code exposes an operation or state that helps a client achieve a goal; other code is internal. section 5.2
- Avoid public implementation details. When the public API extends beyond observable behavior, clients can depend on internals and potentially bypass invariants. section 5.5
Refactor the surface, not the test
A User class exposes NormalizeName publicly, even though clients only need to assign a valid Name. That leaks an implementation detail and forces callers to perform normalization themselves. Move normalization into the Name setter and make NormalizeName private; callers then write user.Name = newName. Similarly, a purchase should be one public operation that both acquires the product and reduces inventory, rather than requiring a second client call. section 3.1
