The API book: API design, patterns and the cost of backwards compatibility

A book that ships from its own repository

The API is a book by Sergey Konstantinov, and the repository is the working repository for it, published at twirl.github.io/The-API-Book.

The framing in the repository's own introduction is worth quoting because it sets the argument of the whole book. API-first development is described as one of the hottest technical topics, since many companies started to realize that an API serves as a multiplicator to their opportunities, but it also amplifies the design mistakes as well.

That asymmetry is the book's premise. An API is a promise, and the cost of getting it wrong is multiplied by the number of clients you did not have when you made the decision. The book is written to share the expertise and describe the best practices in designing and developing APIs.

The structure of the repository matches how a book of this kind gets made. There is a docs directory holding the text, a scripts directory holding the build tooling, a src directory, a jest config and a test script, a TypeScript config, and a ROADMAP.md that documents the current state and the roadmap. The default branch is gh-pages, which is where the published site lives, so the branch you browse is the output branch rather than the editing branch.

The language recorded for the repository is TypeScript, which is not about the prose but about the toolchain that renders it. The primary language of the project is the machinery that builds the book.

The last push was on 2026-06-14 and there are no GitHub releases, since the artefact here is a website rather than a versioned package.

Six sections that follow an API through its life

The book comprises six sections, and the list is the best summary of what it covers.

The first is the API design itself. The second is API patterns, which is where recurring structures such as pagination, filtering, versioning shapes and error handling live. The third is backwards compatibility, the section that a team shipping a public interface will read most carefully, because that is where the cost of an early decision gets priced.

The fourth is HTTP API and REST, the transport and conventions layer. The fifth is SDK and UI libraries, which is about what happens after the interface is designed: the client libraries, the generated code and the design system work that has to follow the same contract. The sixth is API product management, which treats the API as something with users, a lifecycle and a roadmap rather than as an artefact that the backend team owns.

That ordering is the argument of the book. It starts with design decisions and ends with the organisational work required to keep an interface alive, which is a different shape from a reference document that starts with verbs and status codes.

The topics attached to the repository match: api-design, api-patterns, api-best-practices, backwards-compatibility and api-product. There is also backwards-compatibility as its own topic, which is a hint about where the author thinks the difficulty lies.

For a reader deciding whether to spend time on it, the sixth section is the one that decides whether the book is for you. A team that only needs to settle a URL scheme will not get much from API product management, and a team whose product manager is already asking how the interface should be versioned will find the order of the sections useful.

The licence forbids commercial use, and that is explicit

This is an open-source book distributed under the Creative Commons Attribution-NonCommercial 4.0 International licence, and the package manifest records the same thing as CC-BY-NC-4.0 with the licence text in a LICENSE.md file at the root of the repository.

The NonCommercial part is not a detail to gloss over. CC BY-NC 4.0 lets you share and adapt the work, with attribution required, and it forbids commercial use of adapted content. If you want to put the text inside a paid course, inside a commercial training programme, inside a subscription product or inside a consultancy deliverable, that is outside what the licence grants you.

For a company that wants to use the book as an internal reference, the licence is usually fine, because internal reading is not distribution. For a company that wants to turn it into something it sells, it is not, and the workaround is to write your own text, which is what the licence asks.

The repository's own metadata lists the licence as a custom one that GitHub cannot classify, which is a GitHub side effect of the CC licence not matching its dropdown. The substantive position is in the README and the manifest, and both say the same thing: Creative Commons Attribution-NonCommercial 4.0 International.

This is a note on what the licence says rather than legal advice, and for a commercial team the sensible step is to confirm the position with counsel before you circulate the text widely inside the company.

APIDev.rules is the machine readable distillation

Alongside the book, the author publishes API Design and API Review skills distilled from it, at github.com/twirl/APIDev.rules.

This is the part of the project that is aimed at teams rather than at individuals, and the difference is worth understanding. A book teaches you why a decision is right, and the reasoning is what lets you adapt it when your situation differs. A distilled skill is a set of instructions that a tool or an agent can apply, and it trades that reasoning for repeatability.

For a team, that trade is often worth it. A style guide that lives in a document gets read once and then diverges; a set of rules that a review step applies gets applied every time. The API Design skill is the rule set for authoring an interface, and the API Review skill is the counterpart for reviewing one, which is the missing half in most teams, since almost everybody writes guidelines and almost nobody enforces them.

The repository's own topic list includes api-best-practices and api-patterns, which is the vocabulary the rules are expressed in, so the two projects share a terminology rather than inventing one.

The division also clarifies what the book is and is not. The book is a position on interface design argued at length. The rules project is the operational residue. If you want the reasoning, read the book; if you want something a team can run in CI, look at APIDev.rules.

The site is built by scripts that the repository carries

The repository is a working book project, not a folder of markdown, and the build tooling is part of what is published.

The package manifest lists a small set of scripts, and their names describe the pipeline:

    "scripts": {
        "build": "tsx scripts/build.ts",
        "build-landing": "node scripts/build-landing.mjs",
        "docs-server": "node scripts/docs-server 3000",

There is also a script for building version one of the book, one for building the graphs, and one for building the examples, which points at a directory named docs/examples/01. Decomposing UI Components, so the examples are part of the documentation and are generated rather than pasted in.

The development dependencies explain the approach. Puppeteer and jest with ts-jest and jsdom are there for testing, monaco-editor provides the code editor used to present code samples, webpack and ts-loader handle bundling, express serves the documentation locally on port 3000 through the docs-server script, and @twirl/book-builder is the author's own build package, pinned to a specific version.

The illustrations are credited in the acknowledgements, and the list is a good guide to what kind of book this is. There is an illustration and inspiration from art.mari.ka, an Aqueduct diagram by Slepitssskaya, a map by Oscar Hinrichs from the Library of Congress, the coffee icon by lual from Openclipart, and the typefaces: Vollkorn by Friedrich Althausen, Roboto Mono by Christian Robertson and PT Sans by ParaType. Diagrams and type specimens are treated as part of the argument rather than as decoration, and Mermaid is credited for the diagram rendering, along with Figma and the Figma UI Kit by Joey Banks.

One author, no pull requests, typo fixes welcome

The contributing policy is unusual and worth stating before anyone opens a pull request.

The author is accepting inquiries and says to feel free to open issues. He is not accepting pull requests that introduce any new content, since he is willing to be the only author, and he would gladly accept typo fixes.

That is a deliberate choice about a book rather than about a codebase, and it has a defensible logic. A technical book is a claim about how things should be done, and a reference implementation of that claim, in the sense that a second author with a different set of experiences would tend to write a different book inside the same structure. The open issues channel keeps the door open for readers to disagree without fragmenting the text.

It also means this is not a community document in the way most open-source repositories are. If your team wants to fork it and restructure the text, the licence permits adaptation for non-commercial purposes with attribution, and the author preference is not a legal restriction on that, but a new book will not be merged back.

For anyone planning to use the book internally, the practical consequence is that you should treat it as a book to read and argue with, not a document to pull request against. The rules project is the part that is designed to be extended.

The acknowledgements also credit two people for valuable feedback, Ilya Subbotin and Fedor Golubev, which is a reminder that a single-author book is usually the last draft of something several people argued over.

What the book is for, and what it is not

The pragmatic case for reading it is that the six sections describe an API as a product with a lifecycle, and most interface design disputes inside a company are disagreements about lifecycle rather than about syntax. Whether a version field belongs in the path, when a breaking change is acceptable, how an SDK is versioned against the service it wraps: these are product questions, and a book that reaches them early is more useful than one that stops at status codes.

It is also, by its own admission, a position rather than a standard. The author is a practitioner writing about his own experience, the acknowledgements list feedback from two colleagues, and the topics attached to the repository are the vocabulary of his approach. If your organisation already has an interface standard with an owner and an enforcement mechanism, this book is a second opinion, and possibly a useful one, but it is not going to replace what you have.

Where it will not help is as a quick reference. The repository has no releases and no versioned artefacts, and the site is the deliverable, so there is no chapter to skim for a rule you can apply this afternoon.

Two further practical notes. The Russian edition is published alongside the English one at a separate path, index.ru.html, which matters for teams where the working language of the API discussion is not English. And the repository's default branch being gh-pages means that browsing the repository on GitHub shows you the published site rather than the sources, which is a small thing that confuses newcomers looking for the text.

For a team that is designing an interface now, and will live with it for years, that is a reasonable thing to spend a few evenings on.

Editorial conclusion

The API suits a team that is designing an API from scratch, that has to argue about versioning and backwards compatibility, and that wants a single coherent treatment rather than a checklist. It is the wrong choice if you need to publish the book commercially or train a model on it, because the licence is non-commercial, and it is the wrong choice if you want a source of rules you can enforce mechanically, because the distilled skills are a separate project with their own scope. Verify three things before you adopt it as a team norm: that the non-commercial licence fits how you intend to use the text, which the author states plainly, that the six sections match the problems you actually have, and that you are prepared to have the discussion the book prompts rather than to copy the rules without the reasoning.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. twirl/The-API-Book on GitHub