Ok today let’s talk about API. what the fuck is it, what makes a good API, and why APIs have become such a hot topic that even non-tech folks have to care about it.
so when i first came across the word API, it felt like some weird nuance.I kinda knew what it was, but if someone actually asked me “what’s an API?” … bruh, i’d stumble. yeah i could spit out an answer, but it didn’t feel like it came from me. i wasn’t confident, i wasn’t comfortable.
and if you feel the same, if you’re not fully comfy around APIs,then this one’s for you.
what even is an API?
first things first: when we google or ask around, answers about APIs sound different. some say “it’s a well-defined interface where two software applications talk to each other.” others say “it’s a contract, not just technology.”
so… who’s right? actually both.
umm, how do i paint this picture so it sticks?
right!! imagine going to a restaurant. you get a menu. now, this menu shows you exactly what you can order. you can’t just order stuff outside of it. this is like a well-defined interface: you’re shown your options, you don’t need to run into the kitchen asking around. the menu already gives you the “what’s possible.”
now, when you order pasta, you expect pasta. if the waiter brings you rice and curry? chaos. you’d be confused, maybe pissed.
see the parallel? the restaurant gave us a menu aka the API. the menu tells us what’s possible and what we can expect. and we as customers expect the restaurant to actually deliver what we asked for. that’s the contract.
so yeah..an API is both things: a well-defined interface and a contract between provider and receiver. a good API checks both boxes.
ok, cool now, but what makes an API “good”?
now you got the picture of what an api is. not super detailed yet, but enough of a mental image to explore deeper.
and here’s where people usually stumble: most of us aren’t actually designing APIs, we’re just using them. when we build apps or functions, we just consume APIs,our focus is on what we are building.And because of that, we don’t notice or pay much attention to think about the design or structure of the api we use or appreciate it. so when someone asks “what makes a good API?” we blank.
but here’s the shift: think of an API as a software product.
when we hear “software product,” what pops in mind? specifications,backward compatibility, availability and things that relying on it, downtime is a nightmare, versioning and finally ability to evolve.
guess what? same rules apply to APIs.
so, a well-defined API has:
- a clear specification
- a solid contract and it sticks to it
and here’s the thing: with humans, contracts can be flexible. you order pasta, they mistakenly bring curry, you can call it out, they apologize, fix it.
but software? nah. it’s strict. code doesn’t “understand” misunderstandings. if your API promises pasta, it better deliver pasta.
that’s why a good API is all about:
- contract discipline → never betray what you promised
- availability → if your API is down half the time, who’ll use it?
- evolution without breaking shit → business + tech are always moving. APIs need to evolve but still keep backward compatibility so current users don’t break.
of course, sometimes we can’t evolve without breaking old stuff. that’s where API versioning comes in. when you can’t maintain backward compatibility, you roll out v2 (whether via URL versioning or headers). the old consumers keep working, while new ones move forward.
so, a good API is a software product: reliable, backward-compatible when possible, and able to evolve without chaos.
API classifications (not what you think)
so far you’re clear on what an API is and what makes it good. now let’s zoom out to classification.
and no, i’m not talking about REST vs SOAP. those are styles. what i’m talking about is different dimensions of classification.
because APIs aren’t in one big hierarchy with one boss. instead, you can classify them by different aspects:
- by audience → who uses it? public (anyone), private (internal only), or partner (shared with specific parties). the ones you usually meet are public APIs.
- by access medium → what domain it lives in. web API, library API, OS API, hardware API.
- by communication style → how the client talks and how data flows. could be REST (resources + HTTP verbs), GraphQL, or SOAP.
- by package → how it’s delivered. raw endpoint? SDK (ready-made lib)?
- by domain/use case → what problem it solves. cloud API, payment API, social API, etc.
Aight so now you know that infact an single api can be classified under different dimensions and still fall under multiple categories the same time.
sheesh!!that was a whole load of info right?
but now, if someone asks you what an API is, you won’t just parrot some textbook line. you’ve got a full picture, with intuition.
go through this a couple of times if you’re still not comfy.My goal isn’t to cram definitions in to your head instead it’s to have that natural, intuitive feel of “i know what an API really is.”
so until we meet again ✌️
Top comments (1)
Nice machn 👏👏