From Product to API-First

Most of what follows can be decided without a vendor, and should be. The advice holds whichever platform you end up choosing, and most of the pitfalls are organisational rather than technical.

What actually changes

The shift is usually described as technical. It isn’t. What changes is where the value sits.

In a product approach, the value is in the application. You buy a system, it solves a task, and when another task resembles it you buy or build another system. Integrations are made case by case, and each new connection costs roughly what the last one did.

In an API approach, the value is in the contract. You describe once what a capability does, and many things can then use it. The fifth use costs considerably less than the first, and the twentieth costs almost nothing.

That is what makes the approach economically interesting — not the technology, but that the cost stops being linear.

	Product approach	API approach
Unit of value	the application	the contract
Each new consumer	one more integration	the same contract
Cost curve	grows with every connection	paid once

What to plan

Ownership, before anything else

Every API needs an owner who can say what it does, what it promises, and when it changes. This is the single factor that best predicts whether an API effort succeeds. An API without an owner quickly becomes an API nobody dares use, and then an API nobody dares change.

The split between shared and local

Some capabilities are the same everywhere and should be described once. Others are local and should stay that way. Decide the split early and explicitly — otherwise everything becomes either centralised, which makes the centre a bottleneck, or local, which means nothing is reused.

The standard, before the first API

The design standard has to be settled before anything is built. Following a standard from the start is cheap; imposing one afterwards is expensive. Most organisations have API guidelines. Few have adherence to them, and the difference is whether the standard is structured into the work or written in a document.

Versioning as a promise, not a technicality

Decide in advance what you are promising consumers. A reasonable promise is that they integrate once per major version, and that breaking changes never arrive unannounced. That promise is easier to make than it is to restore once broken.

How someone gets access

Access has to be grantable without a project. If getting started with an API takes an email, a meeting and a manual configuration, it will not be used — however good it is.

What to watch for

The catalogue nobody can get into

The most common failure. An overview of APIs is built and published, and then nobody can actually get access to anything in it. A list is not a marketplace. Discovery and access have to be the same flow, or the catalogue becomes documentation rather than infrastructure.

Reuse by committee. Reuse does not happen because a forum decides there should be reuse. It happens when someone can subscribe to a contract without asking a central body for permission. If every reuse needs an approval elsewhere in the organisation, the reuse does not occur — it gets reported as an ambition.

The urge to standardise the technology. It is tempting to mandate a common language and a common platform. It is also the surest way to spend eighteen months in a technical working group. Standardise the contract; let the implementation be local. Two parties can exchange data without agreeing on anything except the interface.

Internal APIs that can never be exposed. If internal and external APIs are built to different standards, the cost is paid at the moment of sharing — precisely when nobody has budget for it. Build everything to the same standard from the start and external exposure becomes a setting you adjust rather than a project.

Breaking changes discovered by consumers. You need to see who is affected by a change before it is released. Without that, every change becomes cautious — and a platform where people are afraid to change anything stops developing.

Confusing integration with API. An integration connects two systems. An API is a capability many can use. Integrations do not accumulate: each new one costs what the last one did. If a programme ends up delivering integrations under an API name, the economic effect never arrives, even though the deliverables look right.

What to expect

The first months feel slower. Describing a contract takes longer than writing an integration. That is real, and worth saying out loud at the start so it is not read as evidence that the approach does not work.

Then the cost drops noticeably. The effect does not arrive gradually but as a step change. The fifth API is substantially cheaper than the first, because the standard, the patterns and the access path already exist.

Reuse shows up as subscriptions, not as reports. You know it is working when someone has adopted an API without asking permission first. It is the one measure that is hard to dress up.

Costs become visible. Consumption can be attributed to whoever consumes it. This is often the first time an organisation can see what a capability actually costs — useful, but also uncomfortable, and worth expecting.

The organisation changes more than the technology does. Ownership, responsibility for promises made to others, and a centrally supported rather than centrally governed model. That is where resistance appears — not in the tooling.

The short version

Decide ownership. Settle the standard before building. Make access self-service. Standardise the contract, not the technology. Let the centre support rather than approve.

Four of those five are organisational decisions.

Where a platform fits

A platform is relevant for the parts where adherence otherwise depends on people remembering to do the right thing: that the standard is applied at design time rather than audited afterwards, that access can be granted without a project, that the consequence of a change is visible before release, and that a service-level promise is enforced rather than merely written down.

The boundary is worth being precise about. Your language, your infrastructure and your code remain yours. What gets governed is the contract and the promise — so that a release does not break the guarantee you gave your own consumers.

See Deployment Models for how far enforcement reaches in each hosting arrangement, which is a decision worth making deliberately rather than discovering later.

What is worth measuring

Agree the success criteria before you start rather than afterwards, or the effort gets judged on whatever each person happens to notice. These four are concrete and can be settled without interpretation.

1. Time to a governed, secured interface. From the scenario existing to a running API with access control, documentation and discovery in place. Measured in hours.
2. The price of consumer number two. What it costs to connect the next party once the first is connected. If that number is not markedly lower than the first, the approach has not worked.
3. A breaking change caught before release. Make a change that would break an existing consumer and see whether the system says so in advance — and names who is affected.
4. Access without a project. Let a party who was not involved in building the API get access and call it, without anyone writing code or configuring anything by hand.

One scenario is enough, and better than three. The point is not to demonstrate breadth, but to make the migration path and the time it takes concrete enough that you can work out the rest yourself.