Lessons from Scale #8: APIs Don’t Integrate Systems. Workflows Do.

Humans have been glue for as long as technology has existed

Every modern system has APIs.

And yet somehow, at scale, work still moves through screenshots, Slack messages, copied IDs, “just rerun it,” and people who remember what happened last Tuesday.

This isn’t because APIs are bad.
It’s because APIs don’t integrate systems.

They expose capability, not intent.

APIs are necessary — and insufficient

APIs answer questions like:

• What can this system do?
• How do I invoke it?
• What shape does the data take?

They do not answer:

• Why is this happening?
• What step are we on?
• What happens if this fails?
• Who owns the decision to proceed?

At small scale, humans fill in those gaps without anyone noticing.
At large scale, humans become the integration layer — quietly, expensively, and unreliably.

That was the core argument of Lessons from Scale #7: Humans Are Not a Scalable Integration Pattern.
Once you remove the human, the question becomes unavoidable:

If not people… then what?

Integration breaks at state, not endpoints

Most “integration problems” are not authentication issues.
They’re not schema mismatches.
They’re not REST vs GraphQL debates.

They are state problems.

• Where does progress live?
• What does “done” mean?
• What does “retry” mean?
• What happens when step 3 succeeds but step 4 fails?
• How do you know whether to continue, compensate, or stop?

When those answers are missing, humans step in. Not because they want to — but because the system gives them no other place to stand.

If your integration requires a person to decide whether a job should be rerun, you didn’t build an integration.
You built a suggestion.

Workflows make intent explicit

Workflows are where intent lives.

They:

• Encode what is supposed to happen
• Track what has happened
• Decide what happens next
• Make failure a first-class concept

This is why workflow engines like Temporal exist — not to draw boxes and arrows, but to durably remember what happened, what should happen next, and how the system should respond when things go wrong.

Without a workflow, APIs are just verbs.
With a workflow, they become sentences.

This is why orchestration becomes a product surface

At scale, orchestration stops being “plumbing” and starts being user experience.

People don’t want:

• endpoints
  
• SDKs
  
• webhooks

They want to know:

• Is it running?
• Did it finish?
• Why did it stop?
• What happens if I change this input?

That’s not an infrastructure concern.
That’s a product concern.

This is why systems like Temporal or AWS Step Functions exist — not because teams love diagrams, but because remembering what happened is a job computers are better at than people.

The moment you scale beyond a single team, workflow visibility becomes non-optional.

Contracts help — but only inside workflows

This is also why things like COGs and STAC work as well as they do.

They succeed not because JSON is elegant, but because they reduce ambiguity.
They act as contracts that workflows can rely on.

A STAC Item doesn’t need a meeting to explain what it represents.
A workflow can reason about it without asking a human to interpret intent.

That’s not accidental. That’s design.

The quiet reappearance of humans

When workflows are missing, humans reappear in predictable roles:

• the job re-runner
  
• the ID copier
  
• the state explainer
  
• the “can you check on this?” messenger

None of those scale. All of them feel familiar.

If your system needs a person to tell another system what just happened, the integration is already broken — it just hasn’t failed loudly yet.

The lesson

APIs are table stakes.
Workflows are the system.

If humans are not the integration layer, then state, intent, and progress must live somewhere else.

At scale, that place is not documentation.
It’s not tribal knowledge.
It’s not Slack.

It’s the workflow.