APIs: the contract between two programs

In the last lesson you split a system into a client that asks and a server that answers. The moment you do that, a new question appears: what exactly does the client send, and what exactly comes back? You and the client are now two separate programs that will be updated on different days, possibly by different people, possibly in different years. Something has to stay fixed between them. That something is the API.

An API (application programming interface) is a contract, and it is worth reading that word literally. It says: if you send this request, you will get this answer. Not "roughly this", not "usually this". A request is built from four things: a method, which says what kind of action this is (GET reads and changes nothing, POST creates, DELETE removes); a path, which says what thing you are talking about (/orders/77); headers, which carry metadata like the content type or a token; and sometimes a body with data. The answer has a status code and, usually, a body of JSON.

GET    /v1/orders/77      -> 200 OK, one order
POST   /v1/orders         -> 201 Created, the new order
DELETE /v1/orders/77      -> 204 No Content, nothing left
GET    /v1/orders/999     -> 404 Not Found, no such order
POST   /v1/orders/broken  -> 400 Bad Request, the body is wrong
GET    /v1/admin/users    -> 401 Unauthorized, no token sent

Status codes are the shared language for outcomes, and there are only a few families you need. 2xx means it worked. 4xx means the request was wrong: 404 for a thing that does not exist, 400 for a body that makes no sense, 401 for a missing or bad token. 5xx means the server broke while handling an otherwise valid request. This split is not bureaucracy; it tells the client what to do next. A 404 is final — do not retry. A 500 might be temporary — retrying is reasonable. Without the split, every client has to guess, and every client guesses differently.

One day the shape of an answer has to change. Perhaps total was the number 12.90 and the business now needs a currency with it, so total becomes an object. Your own page can be updated in the same afternoon; the phone app cannot, because people keep old versions installed for months, and a partner's script may be updated by somebody who has never heard of you. This is the moment you decide whether the change is breaking. If every existing client that does not change its code will now fail, it is breaking, and it needs a new version: /v2/orders/77 next to the old /v1/orders/77, with both served until the old one is finally retired.