Restful-api-guidelines is a comprehensive set of guidelines for designing RESTful APIs and event-driven systems.
The project addresses the challenge of maintaining consistency across APIs developed by different teams. When APIs lack uniform design patterns, adoption becomes difficult and clients struggle to use them correctly. Zalando created these guidelines to establish a shared standard that makes APIs appear as though designed by a single cohesive team. The approach documents best practices and common patterns encountered during RESTful API development, providing concrete answers to recurring design questions rather than abstract principles alone.
Teams building REST APIs should adopt these guidelines when consistency across multiple services matters—particularly in organizations with distributed development teams or public-facing APIs. The guidelines work best for teams willing to challenge their existing API designs against a comprehensive standard. They suit projects where reducing friction between API producers and consumers is a priority. The document is positioned as a living reference rather than a fixed specification, encouraging teams to use it as a starting point for their own API governance while contributing back learnings from their experiences.
The project maintains active development with regular updates reflecting evolving practices and team learnings. Documentation is kept current through automated build processes that validate the guidelines. The maintainers actively refine the content based on real-world application within their organization and community feedback.
