Zalando's guidelines identify every rule with a numbered anchor, and the build image is pinned to latest
A model set of guidelines for RESTful APIs and Events, created by Zalando
At a glance
- What is it?
- The Zalando restful-api-guidelines repository is a book: chapters of AsciiDoc, a rule model, a stylesheet, and a Makefile that lints, checks and renders it to HTML, PDF and an ebook. The rules are not prose headings but numeric anchors, and three separate Makefile targets police them. It is published at two addresses, has no releases, and is licensed CC-BY-4.0.
- Who is it for?
- Use these guidelines as a review checklist rather than as a specification, which is how the project asks you to use them: it says its own teams are encouraged to apply the rules in order to challenge their APIs, and calls the document living and evolving. For a team with several APIs, the numbered rule anchors are the useful part, because a review can point at a rule number rather than at a paragraph.
- Can I use it commercially?
- Yes, with credit. CC-BY-4.0 allows commercial use as long as you credit the authors and indicate what you changed. It is written for creative content, so check how it applies to any code.
- Is it still maintained?
- Yes. The repository last received commits 47 days ago.
- What is it written in?
- Mainly CSS, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- zalando/restful-api-guidelines3,267 ★ · +16
| Repository | 2026-09-24 | 2026-11-15 |
|---|---|---|
| zalando/restful-api-guidelines | 3.3k | 3.3k |
16 Stars in the last 52 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Every rule is a numeric anchor, and the next ID is derived from the highest
The rules in this project are not identified by title. They are identified by numbers.
Each rule carries an anchor of the form a hash sign followed by digits, and the Makefile has a target whose entire job is to work out what the next one should be. It searches the chapters for lines that consist of nothing but such an anchor, sorts what it finds in reverse order, takes the first entry, strips the bracket and hash characters from it, and echoes the result with one added.
That is a generator rather than a counter. There is no stored value to keep in sync, so the next identifier is always one past the highest already present, which means gaps in the numbering are possible and renumbering after a deletion would collide with existing anchors.
The pattern it matches accepts up to five digits, which is the widest bound anywhere in the build. It is a small design decision that shapes every future rule number in the book.
Two checks police the anchors and they test for different things
Rule identifiers are guarded by two separate targets, and they are not looking for the same failure.
The first searches every chapter for anchor patterns, sorts the matches, and asks whether any appear more than once. If a rule number appears twice anywhere in the book, the build stops and tells you to make sure the rule ID anchors are unique. That target guards against a collision, which is the failure that would silently break every cross-reference to a rule.
The second looks for identifiers written in the wrong shape. It matches a bare number in square brackets at the start of a line, with no hash, and also a bracketed number with padding spaces inside it. When it finds one it prints the offending lines and states the required form, an anchor made of a hash and digits.
Together they cover collision and malformation, but neither checks that a number is actually referenced anywhere, so an unreferenced rule and a dangling cross-reference both pass.
The build image is pulled with a floating latest tag
Rendering is done inside a container, and the container is not version-pinned.
ASCIIDOC := asciidoctor/docker-asciidoctor:latestA single variable names the image, a `pull` target fetches it, and the current directory is mounted into it at a fixed path. A default target chains a clean, an HTML build and the rule checks in that order.
The `latest` tag is the whole problem with that line. Nothing in the build records which version of the Asciidoctor image produced a given output, so two people building the same commit months apart can get different HTML from the same sources, and a change in the toolchain shows up as a diff in the book rather than as a build failure.
It is a common shortcut in documentation builds and a defensible one for a book that gets rebuilt on every push. It is still the difference between a reproducible build and a convenient one.
The linter runs over the chapters directory and nothing else
Markdown linting is wired up through a Makefile target with a fix mode beside it.
lint: $(NVM_BIN)/markdownlint
markdownlint --config .markdownlint.yaml chapters/*.adoc;
format: $(NVM_BIN)/markdownlint
markdownlint --config .markdownlint.yaml --fix chapters/*.adoc;Two things stand out. The lint and format targets both depend on a file path built from a variable that is not set anywhere in the visible part of the Makefile, and the recipe installs a command-line linter globally through npm when that path is missing, so the path is effectively decoration and the install is what does the work.
The second is scope. The glob is `chapters/*.adoc`, so linting covers the chapter files only. The book's front matter, its build instructions and its contribution guide are AsciiDoc documents too, and none of them is checked. That is a defensible boundary, as long as nobody reads a green lint run as a statement about the whole repository.
Two published addresses, neither of them a release
The document is readable at two URLs, and the repository advertises one of them while linking the other.
The homepage metadata names an address on the company's open-source site. The README's own line labelled as the latest published version points at a different host, on the project's GitHub Pages address, and labels it as the HTML edition.
Neither address carries a version. The repository has no GitHub releases, so there is nothing to pin a link to and nothing in the way of a changelog entry per version, even though the Makefile has a target that shells out to a script to update one.
For a document meant to be quoted in a design review, the missing version is the part that matters. A rule cited as number such-and-such can be checked against a commit, but a URL cannot tell a reader whether the text they are looking at is the text the rule was written as. MAINTAINERS and a contribution guide sit at the root for the human side of that, and a Zappr configuration file suggests pull request approval is part of the process.
A rule model, chapters, and a stylesheet are three separate directories
The repository is a book, and its layout says which parts are the content and which are the machinery.
There is a chapters directory holding the AsciiDoc sources, an index document that assembles them, a models directory, a resources directory, a scripts directory, an assets directory, a sass directory, and a stylesheet at the root. The build writes into an output directory and an includes directory, both removed by the clean target.
The presence of a models directory is the part that distinguishes this from a folder of Markdown files. The guidelines are held as data as well as prose, which is what lets a Makefile target compute the next rule number and what lets the two anchor checks query the chapters by pattern.
That also explains the declared primary language. With a stylesheet and a sass directory at the root and no source code in the repository at all, the language statistics land on CSS, which is a fair description of what is here and a misleading one about what the project is.
The stated purpose is that good APIs look like one team wrote them
The argument the project makes for itself is short, and it is about consistency rather than correctness.
It says that great RESTful APIs look as though they were designed by a single team, and that following one set of guidelines promotes adoption, reduces friction and lets clients use an API properly. The guidelines are offered to answer the questions that come up along the way, and are shared to invite discussion and refinement within and between teams rather than to be adopted wholesale.
The usage section makes the same offer twice. It invites anyone to use the rules as guidance for their own development, and it encourages the authors' own teams to apply them in order to challenge their APIs. What follows is the sentence that decides how to read the whole thing: this should be considered a living, evolving document, revised and updated as their learnings and experiences change.
That framing is why the numbering scheme matters more than the prose. A checklist that changes needs identifiers people can cite and diff, and that is what the anchor machinery exists to provide.
Editorial conclusion
Use these guidelines as a review checklist rather than as a specification, which is how the project asks you to use them: it says its own teams are encouraged to apply the rules in order to challenge their APIs, and calls the document living and evolving. For a team with several APIs, the numbered rule anchors are the useful part, because a review can point at a rule number rather than at a paragraph. Three things to know before you rely on it. Where the canonical copy lives, since the homepage metadata and the README's own published-version link point at two different addresses and neither is a versioned release. How current it is, since there are no releases at all and the last push to the default branch is dated 2026-09-29. And what the build actually checks, since the linter covers only the chapters directory and the two anchor checks test for different failure modes, so a clean run does not mean the whole book was validated.
Frequently asked questions
What is Zalando's restful-api-guidelines project?
It is a set of guidelines for RESTful APIs and events created by the Zalando Tech team and published under CC-BY 4.0. The stated aim is that great RESTful APIs look as though one team designed them, and the project asks readers to treat it as a living, evolving document revised as the team's experience changes.
How are the rules in Zalando's restful-api-guidelines identified?
By numeric anchors rather than by title. One Makefile target searches the chapters for lines that consist only of a hash followed by digits, sorts them in reverse, takes the highest and echoes it plus one, so the next rule ID is derived from the existing ones instead of being stored. Two other targets check for duplicate anchors and for identifiers written in the wrong shape.
How do I build the Zalando RESTful API guidelines?
The Makefile renders through an Asciidoctor container image pulled with a floating latest tag, mounts the working directory into it, and its default target runs a clean, an HTML build and the rule checks. Markdown linting and a fix mode run over the chapters directory only. Output targets include HTML, PDF and an ebook format.
Where can I read the published Zalando API guidelines?
At two addresses. The repository homepage metadata names an address on Zalando's open-source site, while the README's line for the latest published version points at the project's GitHub Pages address and labels it the HTML edition. The repository publishes no GitHub releases, so neither address carries a version number.
What licence are the Zalando RESTful API guidelines under?
Creative Commons Attribution 4.0, with the licence file at the repository root. The README states the terms and points at that file rather than restating them, which is why the guidelines can be quoted and adapted in another team's own documentation as long as the attribution travels with them.
Does Zalando publish versioned releases of these guidelines?
No. The repository has no GitHub releases, and it is not archived. The last push to the default branch main is dated 2026-09-29, and although the Makefile includes a target that calls a script to update a changelog, there is no release record to attach versions to.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/zalando-restful-api-guidelines)Star history chart for your README
[](https://hysenlabs.com/projects/zalando-restful-api-guidelines)Was this useful?