Last week, a friend asked me something so basic, so fundamental that i should have been able to answer it in my sleep.
"Hey, quick question...what exactly is an API?"
Not a trick question. Not an interview. Just two devs talking.
And I went blank.
I’ve built REST APIs. I’ve authenticated with JWT.
But in that moment? Nothing.
So I did the thing we all do when our brain short-circuits:
"I mean… I know how they work? Or what they do? You know."
We both laughed. He nodded like he understood. But I knew: I had failed the simplest test of all.
The Problem (It’s Worse Than You Think)
When a non-technical person asks “what’s an API?”, you can use a waiter or a mailman analogy. They’ll be happy.
But when a technical person asks, they’re not looking for a metaphor. They already know what a server is, what HTTP is, what JSON is. They’re asking for the essential definition – the crisp, precise, almost philosophical answer.
And that’s way harder.
Because APIs are so obvious to us that we’ve never actually articulated them. We just… use them. The definition lives in our fingertips, not our tongue.
So after that humiliating moment, I went home and forced myself to answer properly. Here’s what I came up with.
What I Should Have Said (Technical Edition)
The One-Sentence Definition (Crisp & Precise)
“An API is a defined interface that specifies how one software component can interact with another – including valid requests, expected responses, and the underlying protocol (usually HTTP).”
That’s the technical answer. No fluff. No waiter.
The Slightly More Technical Answer
“An API is a contract between a client and a server. It says: ‘If you send me a request in this shape, to this URL, with these headers, I’ll send you back a response in this shape – and here are the status codes to tell you what happened.’”
The “Ah, Right” Analogy (Still Technical)
“Think of a database query language like SQL. You send a SELECT statement, you get a result set. An API is the same idea, but over HTTP – and instead of tables, you work with resources (users, orders, products).”
The Shortest Possible Answer
“An API is a layer that abstracts an implementation behind a set of publicly accessible operations.”
That one would have made me sound smart. But I didn’t say it. I said “uh… you know.”
Why Technical People Go Blank on Basic Definitions
It’s not because we don’t know. It’s because:
- We think in use cases, not definitions – “An API is what I call to get user data” is not a definition, it’s an example. But that’s how our brains store it.
- We confuse “how it works” with “what it is” – I could have explained the HTTP request cycle, JSON serialization, status codes, rate limiting, and authentication. But that’s not what an API is. That’s how you use one.
3.We’ve never had to define it – In school, they teach you syntax, not definitions. In work, you just build things. No one ever says “define API” in a sprint planning meeting.
The Real Lesson (For Devs, By a Dev)
Knowing how to build something is not the same as knowing how to define it.
The best developers can do both. They can talk about implementation and they can zoom out to the 10,000-foot definition without stumbling.
So here’s my challenge to you, fellow dev:
Without looking it up, define these terms in one sentence – out loud, right now:
HTTP
JSON
JWT
DOM
TCP
If you can’t, welcome to the club. Let’s practice together.
Call to Action (Your Confession)
Now it’s your turn.
What basic technical question made you go blank in front of another developer?
Drop your confession in the comments. No judgment. Just devs being honest.
This is Confessions of a Dev. We’ve all been there.
