In this chapter
We'll learn why almost no application works alone — payments, SMS, email, mobile apps and partner systems all talk through APIs — and the two roles in every conversation, the API consumer and the API provider, explained as customers and shops agreeing on a price list.
The Problem in Real Life
Month ten. Saturday morning, an email reaches Anna: "I was charged 89.00 but never got my ticket! The show is tonight." — Daniel Brooks. She checks: the payment provider's dashboard says Daniel's payment succeeded at 7:42 PM on Friday. BlueTicket's database has no order for him at all.
By noon, there are fourteen emails like Daniel's — all from Friday evening's big on-sale. Anna calls Daniel, creates his ticket by hand and apologises. Then she and John sit down with one question: how can money arrive at BlueTicket's payment provider, and BlueTicket simply not know?
"Because the money and the ticket live in two different systems," John says. "Ours and theirs. They only know about each other through messages. Today, one of those messages went missing."
Every API can fail. Design for the day it does.
John
One App Doing Everything vs. Many Systems Talking
Nobody builds everything
Payments, SMS, email and maps are hard, regulated jobs. Specialists do them better.
Systems must agree
Two programs built by different companies can only work together if they agree on exact rules.
Messages get lost
When one system depends on a message from another, a lost message means a lost order.
Why Applications Communicate: API Consumers and Providers
The shop analogy: a shop puts up a price list and rules: "these are the things we sell, this is how to ask, this is what you'll get, and this is what happens if we're out of stock". Customers don't need to know how the shop works inside. They just follow the list. An API (Act 12) is that price list for software: the provider publishes it, and consumers use it.
- Why applications communicate: no app does everything itself. BlueTicket talks to a payment provider (cards are heavily regulated — Act 22), an SMS provider and an email provider (delivering messages reliably is a whole industry), its own mobile app, its own internal services (Act 14) — and to venues' systems, which pull sales numbers into their own accounting.
- API — the agreed contract: an API (application programming interface) is the set of rules for how one program can ask another to do something: which addresses to call, what to send, what comes back, and what errors mean. It's a contract: both sides rely on it staying the same.
- API provider — the shop: the provider builds and runs the API, publishes its documentation and keeps its promises. The payment provider is a provider to BlueTicket. BlueTicket is itself a provider to its mobile app and to venues.
- API consumer — the customer: the consumer calls the API and handles whatever comes back — including errors and silence. BlueTicket is a consumer of the payment, SMS and email APIs.
- Two directions of conversation: usually the consumer asks and the provider answers (a request, Act 12). But sometimes the provider needs to tell the consumer something later — "that payment you started has now succeeded". That message travels the other way, and it's exactly the one that went missing on Friday (chapter five).
| API | Provider | Consumer | Used for |
|---|---|---|---|
| Payment API | Payment provider | BlueTicket | Charging cards, refunds |
| SMS API | SMS provider | BlueTicket | Reminders, codes |
| Email API | Email provider | BlueTicket | Confirmations, tickets |
| BlueTicket mobile API | BlueTicket | BlueTicket's mobile app | Browsing, buying, tickets |
| BlueTicket venue API | BlueTicket | Venues' accounting systems | Sales reports |
Friday's payment flow — and where it broke
1. BlueTicket → payment API
start a payment for 89.00 → pay_7Hk2
2. Fan confirms on the provider's page
bank approves
3. Provider → BlueTicket: "pay_7Hk2 succeeded"
✗ never processed for 14 fans
4. BlueTicket creates order + tickets
never happened
How Friday's payment flow works: (1) BlueTicket asks the payment provider's API to start a payment for 89.00 and gets back a payment ID; (2) the fan is sent to the provider's secure page and confirms with their bank; (3) later, the provider calls BlueTicket back with a message: "payment pay_7Hk2 succeeded"; (4) only then does BlueTicket create the order and the tickets. On Friday, step 3 failed for fourteen fans. The money moved; the message didn't arrive.
The lesson already visible: if your system depends on a single message arriving, sooner or later one won't. John writes on the whiteboard: "Never trust one message." The rest of this Act builds up, piece by piece, to a payment flow that can't lose a paid order.
Key Takeaway
Applications communicate because nobody builds everything: payments, SMS, email, mobile apps, internal services and partners all talk through APIs. An API is a contract, like a shop's price list and rules. The provider builds and keeps it; the consumer calls it and must handle errors and silence. Sometimes the provider must call the consumer back later — and a system that depends on one message arriving will eventually lose one.
Why This Matters
Almost every real application is a web of API calls — to payment providers, messaging services, cloud services and internal services. As a developer, you'll spend much of your time on one side or the other of an API, and many of the hardest production bugs happen in the gaps between systems.
To find exactly where the message was lost, Anna needs to follow one API request all the way through — from the moment it leaves one machine to the moment an answer comes back.