Application Programming Interface

There was a stretch of time when the only way for one program to get something out of another was to reach into its insides. If you needed the list of members, you asked for an account on the other system's data store and read the table yourself. If even that was off the table, somebody wrote a nightly job that dumped a file onto a server and left it there for the other side to pick up.

The weakness of that arrangement showed up the moment either side changed something internal. Rename a column from name to user_name and the screens of two other teams and three partner companies stop working on the same morning. The side that made the change had no idea what it had broken. The side that broke had no idea why. When your code leans on somebody else's internals, every wobble on their end becomes a wobble on yours.

Pagedeck lived through a small version of this. Theo started to add a column to the payment records table and then stopped, because nobody could say for certain who else was reading that table. Finding someone who knew took two days, and in the end he created a second table and wrote the same data into two places rather than touch the first one. That is the price of internals that have leaked outward — a one-line change turns into a week of archaeology.

An application programming interface (API) cuts the problem off by putting a counter in front of the building. The insides stay hidden. What gets published is the list of counters you can walk up to, and, for each one, the values it accepts and the values it hands back. Rearrange the tables behind the counter all you like: as long as the counter looks the same, nobody calling it has to change a line. And because the agreement lives in a document, the screen side and the server side can work at the same time instead of waiting on each other, and anything you pull in from another company arrives through the same kind of counter.

The vocabulary under this term splits six ways. One branch is the style of exchange, another is the format that fixes the shape of what travels. A third is running a counter once it is open, a fourth is where the agreement gets written down. The last two are a pair: the change that breaks the agreement, and the property you protect to avoid breaking it.

Style is the branch that decides the shape of the conversation, and there are five of them. What separates them is who speaks first and how precisely you can ask for only what you need.

1. REST — give every piece of data an address and read or write it by calling that address. It is the most widely used style on the web, so it is usually where a team starts.
2. GraphQL — the caller writes out the exact fields it wants and gets back that much and no more. Drawing one screen can drop from five round trips to one, at the cost of more setup for whoever opens the counter.
3. gRPC — a format for services inside one company talking to each other quickly. It trades a human-readable wire format for a machine-readable one and buys speed with the difference.
4. Webhook — the direction is reversed. Instead of the caller asking over and over, the side where something happened sends a message to an address you gave it. If you want to know the instant a payment clears, you no longer poll every minute.
5. WebSocket — the connection stays open and either side can speak at any time. This is what you want when two people edit the same document and one person's keystroke has to appear on the other screen right away.

Format is the branch that fixes the shape of what travels. Opening a counter is not enough on its own; both sides have to agree on how a request announces itself and how a result is read. The nature of a request is carried by an HTTP method, which works like a verb. A read, a create and a delete each arrive under a different verb, so the receiving side knows what is about to happen before it opens the body. The result comes back as a status code, a three-digit number: 200 means it worked, 404 means the thing you asked for is not there, 500 means the far side is broken. The caller reads the number alone and decides whether to retry or wake a person. The body carried by a request or a response is called the payload, and JSON is the format most often used to write one, because it is plain text a person can read when something looks wrong. All three ride together in a single round trip. Creating a document means sending the create verb with a body holding a title and contents, and getting back 201 along with a body containing the number assigned to the new document — a number the caller then uses in its next request.

Operations is the branch for running a counter that is already open. A counter is never finished when it ships, because people keep knocking on it for as long as it stays open. An API gateway collects the entrances of many services into one. Checking who the caller is and writing down what they did happens once at the front door rather than separately inside every service. Rate limiting caps how many requests one caller may send in a given stretch of time. An integration that accidentally fires thousands of calls per second will take the services behind the counter down with it, so a line gets drawn at something like 60 per minute and anything past it is turned away for a while. API versioning is the practice of running the old shape and the new shape side by side when the agreement changes, which buys existing callers time to move.

Documentation is the branch that writes the agreement down. OpenAPI is a standard for describing the list of counters and the values each accepts and returns in a form a machine can read. What separates it from a handwritten manual is that a single file generates the documentation page, the client code and the checking tools. The familiar accident where the manual and the actual behavior have quietly drifted apart gets much rarer.

The last two branches belong together. A breaking change is any change that stops a caller's existing code from working: dropping a field from a response, renaming one, or demanding a new required input. Yesterday's working integration stops today. Backward compatibility is the property pointing the other way — adding the new thing while the old way keeps being accepted. Rather than removing a field, you add one and keep sending the old field alongside it for a while.

The six branches run in sequence. Choosing a style pulls a format along with it, the format gets written down, and once other people start building against what is written, operations and risk begin. A counter nobody calls has no use for the phrase breaking change, and a counter with a hundred callers has little use for anything else.

"Do they have an API for that? If they do, we can wire it up this week."

A question about whether the other side has already published a counter. If yes, the job is plumbing. If no, someone else has to build first, and the estimate moves from weeks to quarters.

"That changes the API contract, so everything built on it breaks. Let's cut a new version."

A flag that the edit under discussion touches an agreement already out in the world. The suggestion that follows is to keep the old shape and publish the new one beside it.

"Let's settle the API document first, then start the screen and the server at the same time."

Fixing the values that will travel means neither side has to sit and wait for the other.

At Pagedeck the phrase came up constantly when an enterprise customer asked to read Pagedeck document lists from their own internal system. Sofia brought the request in and Mia narrowed it to one thing: reading the list of documents. Theo first suggested simply opening the internal counter the app screens already used, then backed away from it. That counter carried extra values only one screen cared about, and once those values go outside, they become part of the agreement too.

So a separate outward-facing counter was built, and what it would return was written down before any of it existed. On the day the document went out, the customer's developer started writing their side against nothing at all, and Theo filled in the server during the same week. A month after launch, when the customer asked for the name of the last editor in the response, the team added a new field and left every existing one untouched. Nothing on the customer's side had to change, and their developer picked up the new field weeks later, on the day they finally needed it. That is what the counter buys: two teams changing at their own pace without either one waiting for permission.

The first mistake is assuming an API you opened is still yours to change whenever you like. The code sits in your repository and you press the deploy button, so it reads as your property. But from the moment a counter is published, its shape is the ground somebody else's code is standing on. Deleting one field from a response is a single line on your side and an outage on three customers' screens without anyone deploying anything. This is why changes to a published counter are handled as amendments to an agreement rather than as edits to a feature: you add instead of removing, and when something truly has to go, you announce it first and split the versions.

The second is expecting an integration to be quick because an API exists. Receiving an address and a document feels like being halfway done, which is where the impression comes from. The time actually goes somewhere else. A key has to be issued and stored safely, calls have to be spread out to fit whatever rate limit applies, and somebody has to decide whether a temporary failure on the far side means retry or stop. It is also common for both sides to call the same thing by different names in different units, and building that mapping table alone eats days. Leave this work out of the estimate and a two-day integration turns into two weeks, which is a reliable first reason for missing a promise made to a customer.