APIs, without the computer science

An API is a request and a response, nothing more mysterious than that. One system asks another system for something in a format they have both agreed on in advance, and the second system answers.

The clinical version

Think of a consult request. You send a specific, structured question to a specific service. You do not get to ask it however you like; there is a form, and the form is the point. The consulting service reads your request, does its work, and sends back a structured answer you can act on. An API is that same pattern between two pieces of software.

The consult metaphor holds further than most tutorials admit:

• The form fields are the request schema. Name, MRN, question, urgency: each has a defined type and allowed values.
• The routing is the endpoint. You do not fax a cardiology consult to dermatology and hope someone reroutes it.
• The turnaround time is latency. Some consults are stat; some are routine. APIs have the same distinction, even when nobody documents it.
• The consult note back is the response payload. Structured enough to act on, or it might as well not have happened.

If you can explain a consult workflow to a medical student, you can explain an API to yourself. The vocabulary is different; the logic is not.

Why it matters here

Health informatics work is mostly about getting systems that were never designed to talk to each other to exchange information reliably. An API is the contract that makes that possible: a defined request format, a defined response format, and an expectation both sides honour.

When that contract breaks (a field renamed, a value type changed, an auth token expired), the two systems stop agreeing, and someone gets paged.

This is why integration projects feel disproportionately fragile. You are not moving data; you are maintaining a treaty between two organisations that may upgrade on different schedules, answer to different regulators, and have different definitions of "patient identifier."

Authentication: who is allowed to ask

Every consult request gets logged with your name on it. APIs work the same way.

Common patterns you will hear about:

• API keys: a shared secret, like a department fax number. Simple, easy to leak, fine for internal low-risk integrations.
• OAuth 2.0: the system asks the user (or an admin) to grant permission, then issues a time-limited token. This is what SMART on FHIR uses for patient-facing apps.
• Mutual TLS: both sides present certificates. Common in hospital-to-hospital exchange where the trust relationship is institutional, not user-level.

In a meeting, when someone says "we need to figure out auth," they mean: who is allowed to request this data, how do we prove it, and what happens when credentials rotate. If nobody can answer the third part, schedule another meeting before go-live.

Clinical translation: an API without proper auth is a consult form anyone in the hospital can submit under your credentials. You would not accept that on the ward; do not accept it in software.

Versioning: when the form changes

Consult forms get revised. New required fields appear. Old checkboxes disappear. If the requesting service still sends the old form, the consult desk rejects it or misfiles it.

API versioning is the same problem. /v1/Patient and /v2/Patient may return different fields. A vendor upgrade that renames birthDate to dateOfBirth without warning will break every downstream consumer that still expects the old name.

Questions worth asking:

• Does this API version explicitly, in the URL or headers, or does it "just change" and hope integrators notice?
• What is the deprecation timeline when a field moves?
• Is there a sandbox environment that mirrors production schema?

Organisations that treat API changes like EHR upgrade communications (detailed release notes, lead time, rollback plan) survive. Organisations that treat them like internal refactors do not.

Failure modes, in clinical terms

APIs fail in predictable ways. Recognising them saves you from debugging mysticism.

Timeout: the consult was sent; nobody answered within the expected window. Clinically: you would call the service. In software: retry with backoff, alert if persistent. Timeouts during patient registration are not "IT problems"; they are patients who do not exist in the lab system yet.

4xx errors (client error): you filled out the form wrong. Bad MRN format, missing required field, expired token. Fix the request. Do not retry blindly; you will spam the logs and annoy the on-call engineer.

5xx errors (server error): the consult desk is on fire. Their problem, but your patient still needs the answer. Retry may help; escalation definitely helps.

Silent partial success: the worst kind. HTTP 200, but half the fields are null because a mapping broke quietly. Clinically: a consult note that says "see above" with nothing above. This is why validation on the receiving side matters as much as sending correctly.

Rate limiting: you sent forty consults in a minute and the service told you to wait. Batch jobs and poorly written polling scripts cause this regularly. The fix is architectural, not "try harder."

What changes once you see it

You will start reading integration diagrams differently. Every arrow between two boxes is a promise about a request and a response. When something is described as well-documented, what is actually being praised is a clear, stable contract.

You will also start hearing vendor pitches differently. "We integrate with Epic" means there is an API somewhere. It does not mean the API does what you need, at the latency you need, with the auth model your security team will approve.

A few terms, demystified

• REST: the dominant API style; resources identified by URLs, operations via HTTP verbs (GET, POST, PUT, DELETE). FHIR is REST-shaped.
• Endpoint: the specific URL you call. /Patient/123 is an endpoint.
• Payload: the data in the request or response body, usually JSON in modern systems.
• Webhook: the other system calls you when something happens, instead of you polling. Like the consult service paging you when the note is ready, rather than you checking the chart every five minutes.
• Idempotent: calling it twice has the same effect as calling it once. Important for retries. You would not admit the same patient twice because the first message got lost; good APIs prevent that too.

None of these require a computer science degree. They require the habit of asking what happens when the happy path fails.

Before the meeting, answer these three

1. What is the request, what is the response, and who owns each side of the contract? If the answer is vague, the project timeline is fiction.
2. How does auth work, and what is the credential rotation process? If nobody knows, add four weeks to the schedule.
3. What does failure look like, and who gets alerted? Silent failures in clinical systems become patient safety incidents. You want this explicit.

That is the whole idea. Everything past this point is detail, and detail you can look up once you know which question to ask.