API Playground
An API is how one piece of software asks another for something — the plumbing under every health app, portal and integration. Start with the idea in plain words, dissect a real request piece by piece, then drive a live practice clinic API that deliberately hands you a 401, a rate limit, a paginated list and a duplicated booking. Covers status codes, API keys vs tokens vs OAuth2, SMART scopes, pagination, webhooks vs polling, retries and idempotency. Synthetic data only.
What an API actually is, with no code on screen — two analogies that map every technical word onto something you already understand, and four everyday hospital jobs shown with and without one.
In one sentence
An API is an agreed way for one piece of software to ask another for something — and get a predictable answer back.
The letters stand for Application Programming Interface, which explains nothing to anyone. The useful idea is simpler: it is a counter. A defined set of questions you may ask, a defined way to ask them, and a system on the other side that decides what you are allowed to know. You never touch the data directly — and that is the point, not a limitation.
The hospital reception desk
You want a patient's next appointment. You do not walk into the records room and rummage through the filing cabinets — you go to the desk, ask in a set way, show your ID, and the clerk brings back exactly what you are allowed to see. The desk is the API: a defined counter with defined questions, standing in front of data you are never given direct access to.
| The technical word | What it is in the story |
|---|---|
| The API | the reception desk itself — the only sanctioned way in |
| A request | the question you ask at the counter |
| The endpoint | which counter you queue at (appointments, billing, records) |
| Authentication | showing your staff badge |
| Authorisation / scope | your badge opens billing but not psychiatry notes |
| The response | the sheet of paper handed back |
| An error | "no such patient", or "you are not allowed to see that" |
| Rate limiting | one person cannot monopolise the desk all morning |
Why a hospital bothers — four everyday jobs, with and without
A clinic emails a spreadsheet of yesterday's referrals to the hospital at 6pm.
The clinic's system posts each referral to the hospital's API the moment it is created.
Timeliness. The spreadsheet is a day old on arrival and nobody knows if it was read; the API delivers in seconds and says whether it was accepted.
A nurse reads a glucose result off a device screen and types it into the record.
The device sends the reading to the record system's API.
Transcription error is the most common data-quality failure in healthcare. Every human retype is a chance to move a decimal point.
A pharmacy phones to confirm a patient's insurance is still active.
The pharmacy system calls the insurer's eligibility API and gets an answer in under a second.
Cost and scale. A phone call costs staff minutes; an API call costs a fraction of a penny and works at 3am.
A hospital gives an analytics vendor a full copy of its patient database.
The vendor calls an API that returns only the fields it is entitled to, for only the patients it may see.
Safety and governance. This is the strongest argument of all — an API is a place to enforce consent, minimum necessary, and an audit trail. A database copy enforces nothing.
Ready for the health-standard version of all this? The FHIR Sandbox applies these same mechanics to real FHIR resources.