Design an interface other teams will build on, well enough to say what each choice commits you to, to change it later without breaking anybody, and to make its failures something a caller can actually handle

Designing an Interface to Call

An interface is a promise that is expensive to withdraw. This course covers naming the things, choosing the operations, saying what went wrong, handling repeats, paging, and changing it after people depend on it.

8 lessons, written and corrected before you arrived. Reading them here needs no account. The first reads the whole way through; the others open and then stop, because a page nobody owns cannot tell who is reading it. Starting the course gives you your own copy, where every idea has problems standing under it and you can ask about any sentence.

Start reading

01Every Awkward Interface You Have Ever Used Was Awkward for the Same Reason, and the Reason Was Decided in the First Half HourThe nouns an interface exposes are chosen once and lived with forever. Here is how to find the real ones, how to tell when you have the wrong ones, and what wrong ones cost.
02There Are Only Two Questions Worth Asking About Any Operation, and Neither of Them Is What It Is Calledopening onlyClassifying every operation by whether it changes anything and by what repeating it does, why that classification decides who may retry, and what to do with the operations that fail both tests.
03Your Error Message Is Read by a Program First and a Human Second, and Almost Every Interface Gets That Order Backwardsopening onlyDesigning a failure response a caller can branch on: the one field that has to be stable, the retryable question, the four classes of failure, and what must never appear in the text.
04The Second Call Is Not a Mistakeopening onlyA caller who never saw your answer has to ask again. Making that safe means a key they generate, a record you keep, and a decision about how long to keep it.
05Counting From the Start Versus Remembering the Placeopening onlyTwo ways to hand back a long list. One is easier to build and quietly loses rows while somebody is reading. The difference is worth understanding before you choose.
06A Limit Is Only Useful If Somebody Can Obey Itopening onlyRefusing a request is easy. Designing a limit that a well-meaning caller can actually keep to, and telling them enough to do it, is the part that gets skipped.
07Hand Back a Receipt, Not an Answeropening onlyWhen an operation cannot finish inside one call, the shape changes: you accept the work, return an address, and the caller learns to live without an immediate answer.
08Add, Migrate, Then Removeopening onlyEvery interface has to change and every change has somebody depending on the old behaviour. The work is classifying the change honestly and sequencing it so both sides can move alone.