API stands for Application Programming Interface, which is one of the least helpful expansions of an acronym in all of technology. Here is the version that actually explains something: an API is a door you deliberately put in the wall of your system, with a lock on it, a sign above it describing what is on the other side, and a record of everyone who walks through.
Mechanically, almost every API you will meet today is an HTTP API. A client sends an HTTP request to a
URL — GET /customers/42 — and the server sends back a response, usually JSON, with a status code
saying how it went. That is it. The entire programmable web runs on a protocol that was designed to
serve web pages, used more or less as intended. The genius of the web API movement was that it did not
invent a new protocol for machines to talk to each other; it just used the one the web already ran on.
The part most definitions leave out is the part that matters most. An API is not just a technical interface — it is an agreement. When you publish one, you are telling other people they can depend on it. They will write code against it, ship products on top of it, and build businesses that break when you change it. That is why so much of the work around APIs is not code at all: it is design, contracts, versioning, documentation, support, and governance. The HTTP part is easy. Keeping the promise is hard.
There is also a side effect of doing APIs that almost nobody sells you on, and it might be the most valuable one: you cannot expose a resource through an API until you have identified it, named it, and understood it. Most organizations have no real idea what they have. APIs are how they find out.
