API-First Architecture: What to Ask Vendors

Your CRM and your accounts package can both be competent products and still leave someone retyping the same customer. API-first architecture is the habit of treating that connection as part of the buying decision, not as a job you discover afterwards. If you want the plain definition of an API, it is in API basics for non-developers. This piece assumes you have seen that, or something like it, and looks at the choices that follow.

What API-first architecture means for a small team

The Government Digital Service describes API-first as designing the connection before the web or mobile screen. Connections are often added after a service exists, as a way for something else to reach the data. Starting earlier means you find the awkward parts while change is still cheap. Once people depend on a connection, large changes get harder, because older versions have to keep working.

For a firm that buys tools rather than publishing them, this is a buying rule. Before you commit to a screen, ask whether another system can reach the records the business must act on, without a person in the middle.

That does not mean every feature is exposed to the internet. Most connections that matter here are private. It also does not mean you throw out tools that already work. API-later is where most firms already are. The point is to stop the next purchase making that worse.

Why a closed tool becomes a trap

A closed tool is one where the only reliable way out is a person: export, paste, fix the columns, send it on. The copies drift, because nothing checks them. The handoff has no trail, so a failed export shows up as an absence. And leaving is a reconstruction: the export may not include the notes, statuses, or history you now depend on. You find that out when you try to go.

A product that advertises an API integration can still be closed in practice. The connection might read and not write, expose contacts but not the notes your team uses, or exist only on a plan you are not on. “Has an API” and “the API can do the operation we would otherwise retype” are different facts.

There is a trap in the other direction. The GOV.UK Service Manual is direct: relying on a third-party API can tie your service’s availability to theirs. You need a plan if they are unavailable, or no longer there. Queue the action, use another path, tell the people waiting. An API is not a promise the vendor will be up, or will still offer the same connection next year.

API-first, or API-later

If the tool is already live, you are in the API-later case. That is normal. How those joins are made is covered in connecting your business databases. The decision here is what not to assume.

Do not design a new process that needs a write the connection cannot do. A read-only connection can feed a report. It cannot be the place a status is updated.

Do not treat “we will add the connection later” as a plan unless someone has seen the documentation and named the missing objects. Later is when the records are messy. A version you rely on, retired with little notice, becomes your problem.

Government teams that publish APIs are told to plan retirement so users are not cut off without warning: notice, a date, and a path onto whatever replaces it. You are the user. Ask a commercial vendor the same question before you depend on them. For the tools you already have, map what the connection can do, and stop at the edge of that map.

What to ask, beyond “is there an API?”

“Is there an API, and what can it actually do?” is the useful question. The stricter test: if you removed the screen, could another system still carry out the operations the business depends on? Ask in writing, before the records move.

Which records can another system read, create, or update? Name the objects. What can the screen do that the connection cannot? That gap is work a person still has to do.

Does a change send a webhook, or must something keep asking? A webhook is how a tool tells you an event happened, rather than waiting to be polled. Polling can be the right design. Pretending you have immediate updates, when you do not, is not.

What are the limits on how often a connection may call, as numbers? How long is an old version supported, and how are you told? Is there a test environment that does not touch live records?

Who authenticates, and can the connection be limited to the records it needs? If those records include personal data, that limit is a GDPR question as well as a technical one. The Government Digital Service treats access control and logging as part of API design, not a later extra. You are still deciding who can pull a customer list out of a tool, and whether you would know.

If the seller cannot answer, or will not show the documentation, believe that. Learn it before the records are in.

Where the connections should live

You do not need an API gateway because a government guide mentions one. The Central Digital and Data Office writes for organisations that build and run their own APIs, and recommends a gateway so access control, rate limits, and logging are not rebuilt each time. Sound advice if you publish several APIs. The wrong first purchase if the problem is retyping between two products.

Start with three decisions.

Which system owns each kind of record. The CRM may own the contact. Accounts may own the invoice. If both can edit the same field, you have scheduled a reconciliation. “Both, and we will keep them in sync” is not an owner.

How a change travels. A webhook when the event matters today. A scheduled, checked pull when the next morning is soon enough. A named person with an export when neither connection exists, accepted as a temporary job. Real-time is a requirement you either have or do not, not a virtue.

Where the connection is looked after. A data pipeline with an owner, a visible failure, and a way to replay a failed day is enough for most teams at this size. A gateway is worth a conversation only when the same checks are being copied into each connection you operate. Not before.

Fernside builds scoped connections between tools you already use. We do not score vendors, and we do not promise a date by which everything will talk. If you are still deciding whether a shortlist can be joined, start with advisory. If the records and the direction of travel are already clear, that is AI systems work. Get in touch with the two tools and the field someone is copying by hand.