01 — What Even Is an API? The Model That Clicked

"A URL that returns JSON" was my whole model of an API, and it took one definition to straighten it out: an API is a contract, a deliberate surface a service exposes so other software can use it without knowing how it's built. [2] The URL-returning-JSON thing is one shape that contract can take, not the definition.

The framing that finally landed: an Application Programming Interface is the interface part doing the heavy lifting [1][2][3]. A service has internals — databases, business logic, file systems, private functions. Instead of forcing every consumer to learn those internals, the service carves out a small, stable set of operations and says "use these, and only these." That carve-out is the API. The consumer (another server, a browser app, a mobile client) talks to the surface, not the guts. Everything good about APIs — stability, security, evolvability — comes from that separation.

The interface, not the implementation

The cleanest analogy I found is a restaurant [2]. The kitchen is the service's internals — chaotic, full of specialized equipment, staffed by people following procedures a customer doesn't need to understand. The menu is the API. It lists what you can order (the operations), declares what each dish contains (the inputs and outputs), and hides how it's cooked. You don't walk into the kitchen; you order from the menu and a dish comes back. If the kitchen replaces its oven, the menu doesn't change — the interface stays stable while the implementation evolves underneath.

That picture is the whole thesis. The consumer never touches the dimmed boxes. It only ever calls the labeled knobs.

Why we bother with one

Once the separation exists, a pile of benefits fall out for free [1][3]:

• Stability. The service team can rewrite the database, swap languages, or restructure internals — as long as the API surface keeps its contract, no consumer breaks.
• Security. Hiding internals means consumers can't reach around the rules. The API is the chokepoint where authentication (who you are) and authorization (what you're allowed to do) get enforced.
• Reuse. One service, many consumers. A shipping service exposed through an API can be called by the web app, the mobile app, and a partner's system, all at once.
• Parallel work. Once the contract is agreed, the team building the consumer and the team building the service can work at the same time, against the spec, instead of one blocking the other.

The "reuse" point is what made APIs ubiquitous. Modern software is largely a graph of services talking to each other through APIs — payment providers, auth providers, AI models, internal microservices. None of it works without that contract layer [2][3].

The contract has a shape

An API isn't a vague promise; it declares specific operations, what they accept, and what they return. A typical entry in the contract looks like:

GET /orders/{id}
  path param: id (string)
  returns: { id, status, total, items[] }
  errors:    404 if not found, 401 if not authenticated

That's a single operation, fully specified. The consumer knows the verb (GET), the path, the input, the output shape, and the failure modes — without ever knowing whether /orders/{id} is backed by Postgres, a flat file, or a call to another API. The shape is the contract; the implementation behind it is the service's private business.

A real API is a collection of these operation specs, plus the rules around them (authentication, rate limits, versioning). Designing an API well is mostly the discipline of choosing those operations, names, and shapes deliberately — which is what the rest of this series is about.

How I use this

The payoff is diagnostic and design-shaped. When something breaks between two services, I now ask first: is this a contract violation or an implementation bug? A consumer sending the wrong shape is a contract problem; a service returning the right shape with wrong data is an implementation problem — and the fix lives in a different place. When designing a new endpoint, the contract framing keeps me honest: I write down the operation, inputs, outputs, and errors before the code, because that's the part the consumer actually depends on. The implementation can change; the contract is what I'm promising.

References

[1] IBM, "What is an API?," 2024. [Online]. Available: https://www.ibm.com/topics/api

[2] Postman, "Getting Started with APIs," 2024. [Online]. Available: https://www.postman.com/what-is-an-api/

[3] Amazon Web Services, "What is an API?," 2024. [Online]. Available: https://aws.amazon.com/what-is/api/