A model set of guidelines for RESTful APIs, created by Zalando
JavaScript Makefile
Latest commit f17dce2 Jan 18, 2017 @hjacobs hjacobs committed on GitHub Merge pull request #181 from zalando/remove-avoid-javascript-keywords…

Remove Avoid Javascript Keywords Rule
Failed to load latest commit information.
api-operation Update ApiOperation.md Oct 11, 2016
changelog added changelog entry from removing javascript keywords rule #167 Jan 18, 2017
common-data-objects clarification on which common field name type is referenced Jan 11, 2017
compatibility Issue #84: change guidance on custom media types. Oct 13, 2016
data-formats Issue #84: move bracket to include "discouraged" in the link Oct 13, 2016
deprecation added general rule on monitoring APIs and renamed api-discovery chapt… Sep 15, 2016
design-principles clarification on the usage of REST Jan 4, 2017
events bugfix: fixed link to Nakadi api Nov 2, 2016
general-guidelines minor editorial Oct 11, 2016
headers improved wording and added/fixed links. Aug 30, 2016
http Merge branch 'master' into improve/explain-diffs-put-and-post Sep 1, 2016
hyper-media Update Hypermedia.md Nov 3, 2016
json-guidelines removed avoid javascript keywords rule #167 Jan 18, 2017
naming oops, forgot one file Aug 25, 2016
pagination Issue #84: change guidance on custom media types. Oct 13, 2016
performance Issue #84: change guidance on custom media types. Oct 13, 2016
references Merge branch 'master' into tenancy-header-wording Apr 20, 2016
resources added: hint to ULID vs. UUID Dec 8, 2016
security fixed buggy security definition example Jan 3, 2017
tooling Added Swagger IntelliJ IDEA Plugin to tooling May 23, 2016
.catwatch.yaml Added catwatch yaml Apr 8, 2016
.gitignore Added Hypermedia standard comparison and changed recommendation to HAL May 25, 2016
.travis.yml removed pdf build to stabilise publishing of gh pages Dec 6, 2016
.zappr.yaml use recommended YAML extension May 11, 2016
BUILD.md updated build documentation Dec 6, 2016
CONTRIBUTING.md added rule to record rule changes in the changelog and that only rule… Oct 12, 2016
Gruntfile.js fixed travis deployment for feature branches May 17, 2016
Introduction.md Elaborate API First Principle and its relation to agile practices Oct 11, 2016
LICENSE Added cc-by license file Apr 8, 2016
MAINTAINERS Added maintainers file Apr 8, 2016
Makefile updated build documentation Dec 6, 2016
README.md add ebook generation guide to readme (#175) Jan 16, 2017
SUMMARY.md updated: principle chapter name Dec 8, 2016
TOC.md Added structured TOC and headers for all rules Nov 25, 2015
api-zalando-small.jpg API icon included Dec 11, 2015
book.json disabled sharing links for social media Dec 6, 2016
package.json updated gitbook plugins Dec 6, 2016


Developing Restful APIs: A Comprehensive Set of Guidelines by Zalando

Build Status Latest published version: HTML


Great RESTful APIs look like they were designed by a single team. This promotes API adoption, reduces friction, and enables clients to use them properly. To build APIs that meet this standard, and to answer many common questions encountered along the way of RESTful API development, the Zalando Tech team has created this comprehensive set of guidelines. We have shared it with you to inspire additional discussion and refinement within and among your teams, and contribute our learnings and suggestions to the tech community at large.


Feel free to use these guidelines as a guidance for your own development. Note that we encourage our own teams to use them in order to challenge their APIs. As such, you should consider this to be a living, evolving document. We will revise and update based on our learnings and experiences.

E-Book Support

You can easily generate PDF, ePub, Mobi files out of our guidelines. Please refer to this explanation - you have to install Callibre. CAUTION: you need to add version 2.6.7 identifier to every build command:

  $ npm install

  # Generate a PDF file
  $ ./node_modules/.bin/gitbook -v 2.6.7 pdf ./ ./api-guidelines.pdf

  # Generate an ePub file
  $ ./node_modules/.bin/gitbook -v 2.6.7 epub ./ ./api-guidelines.epub

  # Generate a Mobi file
  $ ./node_modules/.bin/gitbook -v 2.6.7 mobi ./ ./api-guidelines.mobi

Table of Contents

After a short Introduction, these guidelines include chapters on the following topics:


We have published these guidelines under the CC-BY (Creative commons Attribution 4.0) license. Please see LICENSE file.