Part 1
How systems really talk to each other
The API and integration landscape — a working map for analysts
The slides open in your browser and work with the keyboard: arrow keys to move, N for speaker notes.
A working map of how systems exchange data — REST, GraphQL, gRPC, webhooks, WebSockets, message queues, pub/sub, event streaming, gateways, iPaaS, and the older patterns that still carry a lot of the volume. Plus a framework for choosing between them, and the cases where the right answer is no API at all.
What you will be able to do
- Name the integration styles you are most likely to meet, and say what each is good at
- Tell the difference between an API, an integration, an interface and an event — and why it changes your requirements
- Apply a five-question framework when choosing between synchronous, asynchronous and batch
- Recognise the cases where the right answer is not to build an API
- Place an integration you encounter on a map, and explain where you put it
Prerequisites
None. No coding, no prior API work, nothing to install. If you have sat in a meeting where two systems needed to exchange data, you have enough.
Ask five people in a project what “the integration” is and you may get five answers. One means a REST endpoint, one means a nightly file, one means the whole data flow between two departments. Everyone agrees on the word and disagrees on what sits underneath it, and that often goes unnoticed until the requirements are already written.
This session is my attempt at a shared map.
What you should be able to do afterwards
Place an integration you meet on a single map, and explain why it sits where it does. That is a small thing on paper, and it changes how much you can contribute to a design discussion.
You should also feel able to question the default. “We’ll expose a REST API” is the reflex answer in a lot of organisations, and it is sometimes the wrong one — not because REST is a poor choice, but because the questions underneath it went unasked. Does this data need to move in real time? Can the sender tolerate the receiver being down? Would a file at 02:00 have been enough, and cheaper?
The ground it covers
Vocabulary worth being precise about. API, integration, interface, event, service. These get used interchangeably, and requirements go missing in the gaps. An API is a product with consumers and a lifecycle; an integration solves one specific problem. Those two ideas pull in different directions, and that tension shows up in most real projects.
The shape of the exchange. Synchronous or asynchronous. Real-time, near-real-time or batch. Command or event. These choices decide what happens when the other system is slow, unavailable or wrong — the part of a specification that most often ends up blank, mine included, earlier in my career.
The current landscape. REST as the default and why it earned that. GraphQL, where the client decides the shape of the response. gRPC for internal plumbing. Webhooks and WebSockets. Message queues for decoupling and load levelling. Publish/subscribe. Event streaming as a replayable log. API gateways. iPaaS platforms and the ESB they descend from.
The patterns still running the business. SOAP and XML over HTTP, scheduled file transfers, EDI, direct database integration, batch ETL, mainframe interfaces. In banking and insurance these still carry a large share of the volume, and an analyst who can specify a file interface is more useful than one who cannot.
A framework rather than a preference. Seven axes — coupling, speed, reliability, ownership, complexity, security, cost — reduced to five questions you can ask in a meeting without a whiteboard.
When not to build an API. Ten cases where the honest recommendation is a different mechanism, or none at all. This is easy to skip past, and it is often the cheapest decision available.
Working through it
Three scenarios near the end are meant to be paused on — one-line requirements of the kind that actually arrive: a profile update that must appear downstream immediately, a notification that must arrive reliably but not instantly, a legacy system that can only export overnight. Decide your answer before advancing. Where your answer differs from the next slide is the useful part, and sometimes yours will be better than mine.
About 90 minutes at a comfortable pace. Nothing to submit, nothing to install.
Where this session stops
It is a map, deliberately. It gives you a working vocabulary and a way to choose, not depth in any one technology.
If you want to go further:
- Messaging and asynchronous patterns — Enterprise Integration Patterns (Hohpe & Woolf) is still the reference, and the pattern catalogue is free to browse.
- HTTP itself — the MDN HTTP documentation is more precise than any summary I could write, and worth an hour.
- Anything specific to your own estate — your architects will know constraints no general material can, and the five questions in this session are a decent way to open that conversation.
Next
Part 2 takes a business brief and turns it into requirements a developer can build from. That is where the live demo API comes in.