The menu of requests

Think of it when one program needs something from another, or you are about to change what a program accepts or returns.

In everyday life

A restaurant menu. Diners order only what is on it, and a regular who always orders dish 12 gets a shock when dish 12 quietly becomes a different meal.

One case

A weather service answers one request: send a city, get today’s temperature in Celsius. A phone app has used it for two years. On 1 March the service starts to answer in Fahrenheit, without notice. The app still adds a °C sign, so users in Paris see 57 °C on a 14 °C day.

The unit changed on 1 March; the app did not know
The case, cell by cell1 cell = 1 day
Temperature in Paris (°C)
111312141615
Number the app shows (°C)
111312576159
Days with a wrong number
3
Errors raised
0
The service sent Fahrenheit. The app read every number as Celsius.

Every case

An API is a promise. Once other programs use it, they depend on every detail: the names, the types, the units, what an error looks like. Even an addition can break a strict reader, or code that expects only the values it already knows. The owner sees only their own code, so a change that looks small breaks callers they never meet. That is why many public APIs add a new version instead of changing the old one.

The word

Engineers call this

APIThe list of requests a program accepts from other programs, with the exact shape of each request and each answer. Other programs may use what is on the list, and nothing else.

Treat an API as a promise to strangers. Check every change against its callers, additions too, and change or remove a part only with a new version and a warning.

Where this idea leads

Skills that encode it

  • codebase-design Matt PocockDefines an interface as everything a caller must know: the signature, invariants, ordering and error modes.
  • principle-migrate-callers-then-delete-legacy-apis pstackDeletes an old API in one wave only when “no external users depend on backward compatibility”.