The Diagram and the API Are the Same Kind of Promise

What if the most important similarity between a statistical figure and a software API is not that both communicate information, but that both decide what other people are allowed to see?

A figure turns an unruly analysis into a visual surface. An API turns an unruly system into a callable surface. One may contain regressions, assumptions, and messy data behind it. The other may conceal containers, agents, language runtimes, and undocumented infrastructure. Yet both confront the same design problem: how do you expose enough of a system for others to reason about it without exposing so little that the surface becomes misleading?

This question matters far beyond economics or software engineering. Organizations are increasingly built from systems that most participants cannot inspect directly. Analysts rely on models they did not write. Product teams rely on services they cannot restart. Executives rely on dashboards that compress thousands of decisions into a few lines and colored regions. In each case, the visible interface becomes a substitute for the underlying reality.

The central lesson is this: an interface is not merely a window into a system. It is a contract about what can be known, tested, and trusted. Good figures and good APIs succeed for the same reason. They make hidden structure legible, preserve the right distinctions, and reveal enough of their limitations to prevent confident misuse.

Every Interface Is a Compression Algorithm

A figure is a compression algorithm. It takes a large quantity of observations and analytical decisions, then maps them into a small visual space. An API performs a similar compression. It takes a complex collection of internal capabilities and maps them into a set of names, inputs, outputs, and behaviors.

Compression is useful because nobody can carry the whole system in their head. A reader cannot inspect every observation behind a result during a presentation. A calling program cannot understand every internal implementation detail of a remote service before requesting a function. The interface saves attention by hiding complexity.

But compression always creates a danger: the loss of information may be mistaken for the absence of information.

Consider a line chart showing an estimated treatment effect over time. The line looks simple, but it might depend on sample restrictions, a particular definition of the outcome, clustered standard errors, a reference period, and choices about which observations to exclude. The visual form does not announce all of those decisions. If the figure is well designed, however, it preserves the distinctions that matter most. Uncertainty appears as uncertainty. Comparison groups remain distinguishable. The scale does not turn a small effect into a dramatic one.

Now consider an unpublished API that is fully functional and used by software agents through a Java SDK. To a developer, the service may appear to be a clean set of remote calls. Yet the call depends on hidden assumptions about authentication, versioning, error states, data formats, network availability, and the behavior of the agents running in their containers. A successful request may conceal a great deal of operational complexity.

The surface is not the problem. The problem is unacknowledged compression.

A useful way to evaluate any interface is to ask three questions:

1. What complexity has been removed?
2. Which distinctions have been preserved?
3. What false conclusions become tempting because of the simplification?

These questions apply equally to a chart in a slide deck and a method in a software library. A chart that erases uncertainty invites overconfidence. An API that erases failure modes invites brittle systems. Both may look elegant precisely because they have hidden the information users most need when conditions change.

The quality of an interface is measured not by how much complexity it hides, but by whether it hides the right complexity.

Visibility Is a Form of Governance

When people say that something is visible, they often mean that it can be seen. In practice, visibility is more political and more consequential than that. Visibility determines who can question a result, reproduce a process, detect an error, or propose an alternative.

A figure makes certain claims inspectable. Its axes allow a reader to ask whether the comparison is fair. Its labels allow someone to identify the population being measured. Its markers and intervals allow a skeptical viewer to distinguish an estimate from a precise fact. A good figure therefore distributes analytical power. It gives the audience tools for judgment rather than merely a conclusion to accept.

An API can distribute power in the same way. A published interface tells users what the system can do, how to ask for it, and what to expect in return. Documentation is not cosmetic. It determines whether users can build safely on the service, diagnose failures, and understand the boundaries of its behavior. An undocumented interface may still work, but it concentrates knowledge in the small group that already has access to the implementation.

This creates an important distinction between functional transparency and operational transparency.

Functional transparency means that a system appears to work. A request returns data. A chart renders. A model produces an estimate. Operational transparency means that users can understand the conditions under which the result is valid, the ways it can fail, and the signals that failure is occurring.

Many organizations achieve the first and neglect the second. A dashboard displays current performance but not how metrics are calculated. A remote service responds to calls but offers no public contract. An analysis presents a coefficient but not enough information to reconstruct the comparison. In each case, the system is available without being truly inspectable.

This is why an effective figure does more than decorate a result, and why an effective API does more than expose a function. Both create a shared inspection layer between a hidden process and its users.

The layer must answer questions such as:

• What exactly am I looking at?
• What assumptions produced it?
• What should I do when the expected pattern breaks?
• Which parts are stable, and which parts may change?
• How much confidence should I place in this output?

Without these answers, users are forced to infer the contract from appearances. That is expensive, and it produces a familiar organizational failure: the system works until a new person, a new dataset, or a new environment arrives.

The Most Dangerous Interface Is the One That Looks Complete

A poor interface is not always confusing. Sometimes it is beautifully simple. Its danger comes from suggesting that there is nothing more to know.

Imagine a figure with a single bold line, no uncertainty band, and a carefully chosen vertical scale. It can communicate a strong impression with almost no visual friction. The viewer may leave with a memorable conclusion, but not with a calibrated understanding of how much the evidence supports that conclusion.

Now imagine a software client with one convenient method that hides a chain of remote calls to several agents. The method returns a neat object, so the application treats it like a local operation. But the operation may fail because a container is unavailable, a remote API has changed, a Java dependency is incompatible, or one agent returns an ambiguous response. The clean method signature has encouraged the developer to imagine a cleaner system than the one that exists.

In both cases, the interface has confused ease of use with ease of understanding.

These are different virtues. Ease of use reduces the effort required to perform an action. Ease of understanding reduces the effort required to form an accurate mental model. The first can be achieved by hiding details. The second requires exposing the details that govern consequences.

A practical design principle follows: the more consequential the decision, the more the interface must reveal about uncertainty and failure.

A chart used to choose a marketing color can tolerate more compression than a chart used to allocate public resources. A private internal API may tolerate more implicit knowledge than an interface used by hundreds of independent teams. The right amount of visibility depends on the cost of being wrong.

This suggests an interface risk equation:

Interface risk = consequence of misuse multiplied by invisibility of assumptions.

The equation is not meant to produce an exact number. It is a way of locating attention. If a result has serious consequences and its assumptions are hard to see, the interface deserves more labels, examples, tests, warnings, and documentation. If the consequence is low and the assumptions are obvious, a compact surface may be entirely appropriate.

The principle also explains why “the API exists” is not the same as “the API is usable,” just as “the figure is accurate” is not the same as “the figure communicates responsibly.” Existence describes availability. Usability describes whether another person can act without reconstructing the entire hidden system.

Design for the Moment of Transfer

The deepest test of an interface comes when knowledge moves from one person or system to another. A researcher hands a slide deck to an audience. A team hands a service to another team. An engineer replaces one implementation with another. A new analyst inherits an old report.

At that moment, tacit knowledge becomes the main source of fragility. The original builder knows why a particular category was omitted, which endpoint is experimental, or which error means “retry” rather than “stop.” The recipient sees only the surface. If the surface does not carry the crucial distinctions, the system depends on personal memory.

This is why visual and technical design should be treated as knowledge transfer engineering.

A robust figure carries its interpretation with it. Its title states the claim rather than merely naming the variables. Its axes identify units and populations. Its annotations explain unusual features. Its ordering directs attention toward the intended comparison. It does not require the presenter to supply every essential qualification aloud.

A robust API does something similar. Its names communicate intent. Its documentation provides examples of valid and invalid use. Its responses distinguish missing data from authorization failure and temporary unavailability. Its versioning rules tell users what may change. Its logs and diagnostics help the next engineer see what happened without interrogating the original author.

The common design pattern is self explaining structure. This does not mean that every interface must contain every detail. It means that the details needed for the next correct decision should be present at the point where that decision is made.

For a figure, that may mean showing the confidence interval directly beside the estimate. For an API, it may mean returning a typed error with a retry recommendation instead of a generic failure. For both, the goal is to reduce the distance between an observation and an appropriate response.

A useful audit is to imagine that the creator disappears. Could an intelligent stranger correctly interpret the figure or safely call the service? If not, the problem is not merely documentation debt. It is a design debt. The interface has failed to carry enough of the system's meaning across the boundary.

The real unit of quality is not the artifact itself. It is the quality of the next decision made by someone who did not build it.

Key Takeaways

• Treat figures and APIs as contracts, not ornaments. State what the interface exposes, what it conceals, and what users can reliably infer.
• Make uncertainty visible at the point of interpretation. Use intervals, caveats, typed errors, status signals, and explicit assumptions rather than relying on private explanation.
• Distinguish functional success from operational understanding. A result that appears correct is not enough. Users need to know when it may fail and how to respond.
• Design for transfer. Remove dependence on the creator's memory by embedding names, labels, examples, and failure semantics into the interface.
• Match transparency to consequence. The higher the cost of misuse, the more aggressively you should expose assumptions, boundaries, and failure modes.

The next time you build a slide, do not ask only whether the audience can read it. Ask what they will believe after reading it, and which mistaken belief the design might accidentally reward. The next time you publish a service, do not ask only whether another program can call it. Ask whether another team can understand its limits before production teaches them the hard way.

A figure and an API may seem to belong to different worlds: one persuades human eyes, the other coordinates machines. But both are acts of translation. Both turn hidden processes into public surfaces. Both can either widen participation in knowledge or preserve power behind an attractive facade.

The best interfaces do not eliminate the need for judgment. They make good judgment possible. That is their most important promise, and the one that deserves the most careful design.