An API, application programming interface, is just a documented way for one piece of software to ask another piece of software for data, or to make something happen. When a CRM sends a new contact to an email platform, or an e-shop posts an order to an accounting system, they are using APIs.
Three common patterns
Request / response
One system asks, the other responds: "give me this customer", "create this order". Simple and predictable, but requires one side to know when to ask.
Webhooks
Instead of asking repeatedly, the source system pushes an event to a URL when something happens: "a new invoice was created", "a payment succeeded". Lower latency and more efficient for event-driven flows.
Scheduled sync
Periodic jobs move data in batches, every hour, every night, every week. Useful when freshness is not critical and a push is impractical.
Most real-world integrations combine at least two of these.
What makes an integration reliable
- Clear data ownership. One system is the source of truth for each piece of data. Others receive copies.
- Idempotent operations. Retrying the same call twice produces the same result, essential for webhooks and unstable networks.
- Error handling that is visible. Failures go somewhere a human can see, not into a silent log nobody reads.
- Rate limits respected. Good integrations back off when the other side is slow or throttled.
- Versioning awareness. APIs change. Treat the integration as code that needs updates, not a one-time wiring job.
What makes an integration fragile
- CSV exports emailed around the company and re-imported manually.
- Hardcoded credentials in places nobody remembers.
- One long script that does everything with no retry logic.
- Silent failures, data stops flowing, and nobody notices for weeks.
- Two-way sync without clear conflict rules: which side wins when both changed?
Middleware or direct integration?
There are three main approaches:
- Direct integration: system A talks directly to system B. Simplest for one link, gets messy when there are many.
- Integration platform (iPaaS): a dedicated tool like a workflow platform handles the connectors. Good for simple, common flows; can be expensive and opaque for complex logic.
- Custom middleware: a small internal service that owns integration logic, translations and error handling. Often the right choice when the logic is specific to the business.
The best answer depends on how many systems need to talk to each other, how much custom logic is involved, and whether you want the business rules in a vendor's UI or in code you own.
A concrete webhook example
Say an e-commerce platform should notify your accounting system whenever an order is paid. Instead of polling every minute, the shop calls your endpoint with a small JSON payload:
{
"event": "order.paid",
"event_id": "evt_8f3c21a9",
"occurred_at": "2024-11-12T09:41:07Z",
"order": {
"id": "ORD-10427",
"total": 1499.00,
"currency": "PLN",
"customer_email": "k.nowak@example.com"
}
}The receiving service should accept the request, verify a signature header, store the event_id, and return 200 quickly. Actual work, such as creating an invoice, happens in a background job. If the same event arrives twice, the stored event_id prevents a duplicate invoice.
Rule of thumb: webhook handlers should acknowledge fast and do work asynchronously. Anything slow or fragile, a third-party API call, a PDF render, belongs in a queue, not in the HTTP handler.
Handling retries without duplicates
Every reliable integration needs an idempotency key. A minimal pattern in pseudo-code:
async function handleOrderPaid(event) {
if (await seen(event.event_id)) return; // already processed
await markSeen(event.event_id);
await queue.enqueue('create-invoice', event.order);
}Common mistakes
- Integrating too early. If the process isn't stable, the integration will encode the mess and make it harder to change.
- Two-way sync by default. One-way is simpler and often enough, only go two-way if the business really needs it.
- No monitoring. An integration without alerting is a silent failure waiting to happen.
- Tight coupling. Changes in one system shouldn't break all the others. Keep a translation layer.
A realistic approach
- Draw the data flow: which system owns which field, and who needs copies.
- Start with the most painful single flow and build it one-way first.
- Use webhooks where low latency matters, scheduled sync where it doesn't.
- Add monitoring from day one, not after the first outage.
- Document credentials, endpoints and ownership, so the integration survives staff changes.
