Zalando RESTful API Guidelines: An Open Handbook for API Consistency

What the Zalando Guidelines Are and Who They Serve

The Zalando RESTful API Guidelines is a document that defines how Zalando Tech designs its REST APIs and event interfaces. The README states the core motivation directly: great RESTful APIs look like they were designed by a single team. When multiple teams build APIs without shared conventions, the result is endpoints that are inconsistent in URL structure, response shape, error format, and authentication method. This document defines those conventions so that any Zalando API can be integrated by a consumer who has used any other Zalando API.

The repository description specifies coverage of both RESTful APIs and events, which distinguishes it from most REST-only guidelines documents. The guidelines are published at opensource.zalando.com/restful-api-guidelines/ for external teams to use as a reference, a starting point, or a document to fork and adapt under its CC-BY 4.0 licence.

The README describes the document as living and evolving, revised based on the team's learnings. It encourages internal teams to use it as a challenge mechanism for their existing APIs, not a static standard to satisfy once and ignore.

Document Organization: Numbered Rules, Chapters, and Outputs

The source is written in AsciiDoc format and lives in the chapters/ directory. The main entry point is index.adoc at the repository root. Additional resources such as models and supporting files sit in models/, assets/, and resources/ directories. CSS styling is preprocessed through Sass in sass/.

The Makefile reveals that the guidelines are structured around numbered rules, each identified by a unique anchor in the format [#123]. The Makefile includes two validation targets: `check-rules-duplicates`, which uses grep to find any rule IDs that appear more than once across the chapters, and `check-rules-incorrects`, which checks that every rule anchor matches the canonical format. A `next-rule-id` target outputs the next unused rule number, indicating that rules are never renumbered once assigned.

The build produces three output formats: HTML, PDF, and EPUB. The MAINTAINERS file and a CONTRIBUTING.adoc document for external contributions are also included. A .zappr.yaml file configures Zappr, a GitHub pull request quality gate tool from Zalando, which suggests the repository enforces review requirements on incoming changes.

Building the Guidelines Locally

The build uses Asciidoctor via Docker, which means the only host dependency is Docker or Podman. The Makefile first pulls the official Asciidoctor image:

make pull

Then the default build produces HTML and rules output:

make html

Generated files land in the output/ directory. A lint step using markdownlint is also available for checking chapter AsciiDoc files:

npm install --global markdownlint-cli
make lint

The BUILD.adoc file at the repository root documents the full technical build details, including how to produce PDF and EPUB outputs. The Makefile provides a `changelog` target that runs scripts/changelog.sh to update the changelog, and a `watch` target (listed in the Makefile but truncated in available content) presumably runs a live-reload development server.

Event API Coverage: REST and Beyond

The repository description explicitly names both RESTful APIs and events as the scope of the guidelines. This is notable: many publicly available REST API guidelines focus only on synchronous HTTP request-response patterns and treat messaging or event-driven APIs as out of scope.

Zalando's inclusion of events in the same document reflects the reality of a large-scale e-commerce platform where some operations are initiated asynchronously. The README does not describe the events section in detail, and the chapter contents are not reproduced here; the full coverage of event topics is available only by reading the published document at the homepage URL.

For teams building systems that mix REST endpoints with event-driven components, the dual scope makes the guidelines relevant to both API surface types without requiring separate standards documents.

Adopting the Guidelines in Your Own API Program

The CC-BY 4.0 licence explicitly permits reuse, adaptation, and redistribution with attribution. An engineering team that wants to establish its own API standards can fork the repository and modify the chapters to reflect their own conventions, while keeping the Zalando attribution. The structure of numbered rules with unique IDs is well suited for referencing in code review: a reviewer can cite a rule ID rather than quoting the text.

The README encourages teams to treat it as a challenge mechanism for existing APIs, which implies a process of reviewing each current API against the rules and identifying deviations. The living-document model means the guidelines will continue to change; teams that adopt a fork should decide whether to track upstream changes or maintain a stable internal fork.

Contribution is documented in CONTRIBUTING.adoc. A CONTRIBUTING.adoc at the root means external contributors have a formal path to propose changes, which increases the chance that real-world edge cases get addressed over time.

Limitations: Content Depth and No Version Pinning

Because the repository has no GitHub releases, there is no mechanism for pinning to a specific version of the guidelines. Teams that adopt the document as a standard will need to track the commit history to audit what changed between a known stable state and the current version. There is no changelog format that maps to a tagged release.

The README does not reproduce the actual guideline rules. The document covers REST API design and event API design, but the specific rules on URL structure, naming conventions, HTTP method usage, error response format, pagination, versioning, and events are accessible only through the published HTML at the project's homepage or by cloning and building the repository. A team evaluating the guidelines for adoption must read the full document before committing to it.

The BUILD.adoc file is listed as the technical reference for building the document, but its contents are not included here; teams who want to customize the PDF output or add extensions to the Asciidoctor pipeline should read it directly.

Comparison with Microsoft REST API Guidelines

Microsoft maintains a publicly available set of REST API guidelines in a GitHub repository under the microsoft organization. Both documents aim to establish consistent API design conventions across a large engineering organization and both are published for external use.

The most significant difference is in scope and origin context. Microsoft's guidelines were shaped by the patterns used in Microsoft's cloud services, particularly Azure and Microsoft 365, which use URL conventions and versioning strategies tied to those platforms. Zalando's guidelines reflect the conventions of a European e-commerce company and include event API coverage alongside REST.

Both documents are freely available for teams to read and adapt. The choice between using one as a starting point comes down to which domain context is closer to a given team's situation. A team building APIs for an e-commerce or marketplace product will find Zalando's framing more immediately applicable. A team building APIs that must integrate with Microsoft's cloud services will find Microsoft's guidelines more directly aligned.

Editorial conclusion

Engineering teams looking for an opinionated, battle-tested starting point for their own API design standards will find the Zalando guidelines a practical foundation. The CC-BY 4.0 licence means the content can be adapted and redistributed with attribution. Teams whose APIs are heavily event-driven should read the full document at opensource.zalando.com/restful-api-guidelines/ before adopting it as a standard, since the events coverage is listed in the description but not elaborated in the README.

Frequently asked questions

Official sources

1. Issues
2. License: CC-BY-4.0
3. Project website
4. README
5. zalando/restful-api-guidelines on GitHub