APIs are the new integration layer

Well-designed interfaces let systems work together without fragile links. For years, most organisations connected their systems one pair at a time: a nightly file export from the finance system to the warehouse, a script that copied customer records into the marketing tool, a direct database connection someone set up years ago and nobody fully understands.

Those links work until they do not. A field is renamed, a server is moved or a supplier upgrades their software, and data quietly stops flowing. The more systems an organisation runs, the more of these connections it accumulates, and the harder each change becomes. Application programming interfaces, or APIs, offer a better way, but only if they are designed with care.

Why point-to-point links become a burden

Each direct connection between two systems is built for one purpose, often by whoever needed it at the time. There is rarely documentation, monitoring or an owner. When five systems each connect to the other four, there are twenty links to maintain, each with its own quirks.

The real cost appears when the business wants to change. Replacing a single system means finding and rebuilding every link that touched it. Many replacement projects take far longer than planned for exactly this reason: the hard part is not the new system but everything connected to the old one.

Design for clarity

Use consistent, documented interfaces. A good API is a clear contract: it says what you can ask for, what you will get back and what happens when something goes wrong. When that contract is consistent across an organisation, with the same naming conventions, the same approach to errors and the same way of handling dates and identifiers, developers can connect a new system in days rather than weeks.

Clarity also means designing around business concepts rather than database tables. An interface that offers “customers”, “orders” and “invoices” is easier to use and more stable than one that exposes the internal structure of a particular system. When the system underneath changes, the interface can stay the same.

• Publish documentation that a developer outside the team could follow without help.
• Use the same conventions for names, dates, errors and paging across all your APIs.
• Provide examples and a test environment so others can try before they build.
• Name an owner for each API who answers questions and approves changes.

Version carefully

Avoid breaking users when you change. Once other systems depend on an API, every change carries risk. Removing a field, renaming it or changing what it means can break applications you may not even know exist, including partners’ and customers’ systems.

The usual discipline is simple. Add new things freely, because adding a field rarely breaks anyone. Never remove or change existing behaviour without a new version. When a new version is released, keep the old one running for a published period and tell users well in advance when it will be switched off. Track who is still using old versions so that you can contact them directly.

This takes effort. Running two versions side by side means more testing and more support. The alternative, breaking partners without warning, costs far more in lost trust and emergency fixes.

Monitor use

Track errors and performance. An API that fails silently is worse than one that fails loudly, because the problem surfaces days later as missing orders or wrong invoices. Monitoring should tell you how many requests each API receives, how long they take, how many fail and who is calling.

That information is useful beyond fault-finding. It shows which interfaces are most valuable, which are barely used and could be retired, and which consumers might be affected by a planned change. Set alerts on error rates and response times so the team hears about problems before customers do.

Once we could see which systems were calling which interfaces, retiring the old warehouse system stopped being a leap in the dark. We knew exactly who to talk to.

IT director, wholesale client

Treat APIs as products

The organisations that get most value from APIs treat them as products with users, not as technical by-products of a project. Each important interface has an owner, a roadmap, documentation and a way for users to ask for changes. Its success is measured by how easily others can use it.

This shift has a cost. It takes time from development teams and needs some central guidance on standards. It does not need a large platform or a dedicated department to begin. Start with the two or three systems whose data the rest of the business most often needs, typically customers, products and orders, and put a clean, documented, monitored interface in front of each. New integrations then connect through those interfaces rather than directly to the systems behind them.

A practical first step is to map how data currently moves between your five most important systems. Mark each link that has no owner, no documentation or no monitoring. That map will show where a well-designed API would remove the most fragility, and it will make the next system replacement far easier to plan.

Source: Intelliversal analysis.

Frequently asked questions

Do we need an API management platform?

Not to start. Clear standards, documentation and basic monitoring matter more. A management platform becomes useful once you have many APIs, external partners or a need for usage-based access control.

How long should we keep old API versions running?

Long enough for users to move comfortably, often six to twelve months for external partners and less for internal teams. Publish the date in advance and contact remaining users directly.

Should every system have an API?

Prioritise the systems whose data many others need, such as customers, products and orders. Systems used in isolation may not need one until a real integration need appears.

Explore Custom Application Development