https://github.com/zalando/restful-api-guidelines

A model set of guidelines for RESTful APIs and Events, created by Zalando
https://github.com/zalando/restful-api-guidelines

api documentation guidelines rest-api restful restful-api zalando

Last synced: 6 months ago
JSON representation

A model set of guidelines for RESTful APIs and Events, created by Zalando

• Host: GitHub
• URL: https://github.com/zalando/restful-api-guidelines
• Owner: zalando
• License: cc-by-4.0
• Created: 2016-04-01T15:06:54.000Z (over 9 years ago)
• Default Branch: main
• Last Pushed: 2025-04-22T15:51:49.000Z (6 months ago)
• Last Synced: 2025-04-22T16:45:50.001Z (6 months ago)
• Topics: api, documentation, guidelines, rest-api, restful, restful-api, zalando
• Language: CSS
• Homepage: https://opensource.zalando.com/restful-api-guidelines/
• Size: 27.9 MB
• Stars: 2,912
• Watchers: 74
• Forks: 413
• Open Issues: 17
• Metadata Files:
  • Readme: README.adoc
  • Contributing: CONTRIBUTING.adoc
  • License: LICENSE

Awesome Lists containing this project

• awesome-rest - Restful API Guidelines by Zalando - Developing Restful APIs: A Comprehensive Set of Guidelines. (Design / Guidelines)
• jimsghstars - zalando/restful-api-guidelines - A model set of guidelines for RESTful APIs and Events, created by Zalando (CSS)
• awesome-arsenal - restful-api-guidelines - RESTful API 指南。 (资源 / 指南)
• StarryDivineSky - zalando/restful-api-guidelines - api-guidelines项目是一套全面的RESTful API和事件设计规范，旨在通过统一标准提升API的可维护性和一致性。项目核心包括资源命名采用复数形式、版本控制通过URL路径实现、状态码严格遵循HTTP语义、分页参数使用page和per_page、错误响应包含详细结构和超媒体链接。特色模块涵盖安全措施如认证机制和速率限制、事件设计强调JSON格式与消息队列解耦、超媒体链接增强资源发现能力。工作原理基于模块化架构，通过定义资源、行为、状态码等规范，结合事件驱动设计原则，确保API与事件系统交互时的可靠性与扩展性，同时提供过滤参数标准化、请求限速等实用设计模式，适用于需构建高可用、易扩展的微服务架构场景。 (后端开发框架及项目 / 后端项目_其他)

README

          
= Developing Restful APIs: A Comprehensive Set of Guidelines by Zalando

https://github.com/zalando/restful-api-guidelines/actions/[image:https://github.com/zalando/restful-api-guidelines/actions/workflows/build.yml/badge.svg[Build status]]

Latest published version:

http://zalando.github.io/restful-api-guidelines/[*HTML*],

== Purpose

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.

== Usage

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.

See link:BUILD.adoc[BUILD documentation] for technical details.

== License

We have published these guidelines under the CC-BY (Creative commons

Attribution 4.0) license. Please see link:LICENSE[LICENSE file].