Some APIs look simple because each method is simple. The difficulty appears only when you try to use them: configure() must run before connect(), connect() before start(), and stop() is valid only after startup succeeds.
When correctness depends on operations happening in a particular order, the code has temporal coupling. The word temporal refers to time or sequence: one operation is valid only because another operation happened earlier.
Temporal coupling is not automatically a design flaw. Many real processes have genuine ordering constraints. The engineering problem is hidden temporal coupling: callers must remember an important sequence that the API does not make clear or enforce.
This article shows how to recognize that problem, decide whether the ordering is essential, and redesign an API so callers have fewer invalid sequences available to them.
Think in terms of valid states
Consider a report exporter with this interface:
exporter = Exporter()
exporter.setDestination("archive")
exporter.setFormat("pdf")
exporter.export(report)Suppose export() fails unless both configuration methods ran first. The object can therefore exist in several states:
created
├─ destination only
├─ format only
└─ fully configured → ready to exportThe caller sees one Exporter type in every state, but not every method is valid in every state. That mismatch is the core problem.
A useful mental model is:
Temporal coupling exists when an operation’s validity depends on relevant history that the current interface does not express clearly.
The history might be “configuration happened,” “authentication succeeded,” “a transaction began,” or “the resource has not been closed.” Thinking in states makes that history concrete.
First ask whether the sequence is necessary
Before adding state machines or new abstractions, question the ordering itself.
In the exporter example, destination and format are required before any useful work can happen. There may be no reason to create a half-configured exporter. Passing those values at construction removes two intermediate states:
exporter = Exporter(destination="archive", format="pdf")
exporter.export(report)Now construction establishes the invariant that every Exporter has the configuration needed for export. The caller no longer has to remember two setup calls, and export() no longer needs to discover missing configuration late.
This is often the smallest useful fix: move required information to the point where the object becomes usable.
The same reasoning applies to functions. Instead of this:
request = Request()
request.setEndpoint(endpoint)
request.setCredentials(credentials)
response = request.send()an API may accept required values directly:
response = sendRequest(endpoint, credentials)The second shape is simpler when the intermediate object has no useful independent lifecycle.
Separate essential order from accidental order
Some sequences cannot be removed because they represent the real process.
A file-like resource, for example, may need to be opened before it can be read and closed after use. A transaction must begin before it can be committed. A network session may require a successful handshake before application messages are accepted.
Those are essential constraints. The design should expose them clearly rather than pretending operations are independent.
Other sequences exist only because of implementation choices. Requiring callers to invoke loadDefaults() before applyUserSettings() might be accidental if one buildSettings(defaults, userSettings) operation can perform both steps internally.
Ask two questions:
- Does the domain or external resource require this order?
- Or does the current implementation merely happen to require it?
If the order is accidental, remove it when the resulting API stays understandable. If it is essential, represent it deliberately.
Make state transitions explicit when order is real
Suppose a batch job genuinely has two phases: prepare a validated plan, then execute that plan. A single mutable object might expose this API:
job = BatchJob()
job.addInput(a)
job.addInput(b)
job.prepare()
job.run()What happens if run() is called before prepare()? What if addInput() is called after preparation? Runtime checks can reject those calls, but the interface still offers them.
A clearer design can represent the phases as different concepts:
builder = BatchJobBuilder()
builder.addInput(a)
builder.addInput(b)
plan = builder.prepare()
result = plan.run()prepare() now returns a PreparedBatch rather than mutating the builder into an invisible new state. Only the prepared value exposes run().
The important idea is not the class names. It is that a successful transition produces a value whose available operations match the new state.
In languages with expressive static type systems, distinct types can make some invalid call sequences impossible to type-check. In dynamically typed languages, separate objects still improve discoverability and can reduce accidental misuse, although invalid values may still need runtime validation.
Keep failure semantics attached to transitions
Real transitions can fail. Preparation may reject invalid input; opening a resource may fail; authentication may be denied.
That means a state-changing operation should make success and failure unambiguous. Consider:
session.authenticate(credentials)
session.send(message)If authenticate() can fail silently while leaving session unauthenticated, the next call depends on hidden history and hidden failure state.
A stronger shape returns the usable state only on success:
authenticated = session.authenticate(credentials)
authenticated.send(message)If authentication fails, no authenticated value is produced. The exact error mechanism depends on the language—an exception, result value, or another explicit error channel can all be reasonable. The general principle is that failure must not make an invalid transition look successful.
Do not encode every lifecycle as a new type
Explicit state types have costs. They add names, interfaces, conversion points, and sometimes generic or ownership complexity. For a small local component, that ceremony can be harder to understand than one object with a straightforward runtime guard.
Consider a tiny iterator-like helper:
cursor.next()
cursor.current()If current() is invalid before the first successful next(), introducing UnpositionedCursor and PositionedCursor types may be excessive when the API is private, used in one place, and already obvious to its callers.
A runtime check can be appropriate:
current():
if not positioned:
raise InvalidState("call next() before current()")
return itemThe trade-off is where the complexity lives. Distinct states move complexity into the API structure. Runtime checks keep the API smaller but detect mistakes later.
Prefer stronger state representation when misuse is costly, the API has many callers, valid sequences are difficult to remember, or state-specific operations differ substantially. Prefer a simpler guarded object when the lifecycle is short, local, and easy to understand.
Watch for partial initialization
One common source of temporal coupling is an object that is constructed before it is valid.
Warning signs include fields that begin as null but are logically required, methods named initialize, setup, or configure that must run exactly once, and repeated checks such as:
if dependency == null:
raise NotInitialized()Sometimes delayed initialization is unavoidable—for example, when a dependency can only be acquired later. But if all required values are already available at construction time, partial initialization creates states the program does not need.
Removing those states has a direct consequence: fewer methods need defensive checks, fewer tests are needed for impossible setup sequences, and callers have less lifecycle knowledge to carry.
Watch for boolean state machines
Another warning sign is a group of booleans trying to describe a lifecycle:
connected = true
started = false
closed = falseThree booleans can represent eight combinations, even if only three combinations make sense. Code then accumulates conditions to reject impossible combinations.
When states are mutually exclusive, one explicit state value is usually easier to reason about:
state = CONNECTEDThis does not by itself remove temporal coupling. It makes the lifecycle explicit inside the implementation. You can then decide whether the public API should also expose state transitions more clearly.
Test the rules the API cannot enforce
A redesigned interface may prevent some invalid sequences structurally, but tests still matter.
For the BatchJobBuilder example, useful tests include:
- invalid inputs prevent
prepare()from producing a prepared plan; - a prepared plan contains the validated inputs expected at execution time;
- execution failure does not silently turn a failed run into a successful state;
- mutable builder changes after preparation cannot unexpectedly alter an already prepared plan, if the design promises that isolation.
Notice that these tests focus on remaining behavioral guarantees. If run() simply does not exist on the builder, a runtime test for “running before preparation fails” may no longer be necessary in a statically checked design because that sequence is outside the interface.
A practical redesign process
When you encounter an order-dependent API, start with the simplest intervention that removes meaningful risk.
First, write down the valid states and transitions in plain language. This often reveals that several apparent states are just incomplete initialization.
Next, identify required data. If callers already possess it, require it when constructing or invoking the usable operation instead of collecting it through mandatory setup calls.
Then separate accidental sequencing from essential sequencing. Collapse accidental steps behind one operation. For essential transitions, consider returning a new state-specific value rather than mutating one object while keeping the same interface.
Finally, decide how much enforcement the context deserves. Public or widely reused APIs benefit more from making invalid sequences difficult to express. Small internal helpers can reasonably rely on clear naming and runtime checks when stronger modeling would add more complexity than it removes.
Conclusion
Temporal coupling is easiest to manage when you stop treating call order as an instruction callers must memorize and start treating it as a question about valid states.
Remove unnecessary states by requiring essential data early. When sequencing reflects a real lifecycle, make transitions visible and make failed transitions unambiguous. Use distinct state-specific values when preventing misuse justifies the extra structure; use simple runtime guards when the lifecycle is small and local.
The practical goal is not to eliminate every ordered operation. It is to ensure that important ordering rules live in the design instead of only in the caller’s memory.