API design

Good API design is fundamentally about managing the boundary between a caller and an implementation. The shape of that boundary determines how much cognitive load the caller carries and how freely the implementation can change.

One axis is surface area. Go Monk’s analysis of deep modules frames this directly: a small interface hiding a large implementation is better than a large interface hiding a small one. Shallow interfaces leak complexity outward; deep ones absorb it. The same logic applies to Angular component design, where Kobi Hari argues that components bloated with dozens of inputs should shed concerns into directives and sub-components so each piece of the public surface stays coherent.

Another axis is type fidelity. Angular’s Signal Forms documentation recommends specific types over general ones, avoiding undefined in form models, and drawing an explicit boundary between the form model and the domain model. That boundary does real work: it prevents transport-layer concerns from bleeding into business logic. Zod operationalizes this at runtime. Daniel Sogl’s guide to Angular API validation shows how schema validation with a custom RxJS operator catches unexpected backend shapes at development time rather than as silent runtime failures, and Orval is noted for generating fully-typed API clients from OpenAPI specs — pushing type contracts as close to the wire as possible.

Data format choices also shape what an API exposes. The YAML Norway problem is a concrete example of how implicit type coercion in a serialization format — NO parsing as false — creates silent misbehavior that propagates across every system consuming that format. Predictable, explicit types matter at the protocol level, not just in application code.

Abstraction quality matters too. Conductor’s wrapper over QuickBooks Desktop illustrates what a well-designed abstraction layer looks like in practice: it hides qbXML, SOAP, and the Web Connector behind a typed Python, Node.js, and REST surface, giving callers 130+ object types without exposing any of the underlying protocol complexity.

Finally, the MCP-as-GUI argument raises a context-specific version of the surface-area question: for AI agents that can write code, a heavyweight tool-based interface imposes token costs and composability constraints that a direct API call would avoid. The right API design depends on who the caller is.