[ADP-601] Event as part of API design
Guidance
- SHOULD treat events as first-class citizens in the API design.
- SHOULD design events as a natural part of the API design process.
- SHOULD use a consistent format for events. Here we choose JSON as the event format.
- SHOULD maintain backward compatibility for events.
- SHOULD register event schemas in a centralized schema registry.
- SHOULD trace events.
- SHOULD consider security and privacy for events.
- SHOULD ensure event processing is idempotent.
- SHOULD document events thoroughly, including their purpose, structure, and usage.
- SHOULD provide clear versioning for event schemas.
- SHOULD implement monitoring and alerting for event processing failures.
- SHOULD ensure events are designed to be scalable and resilient.
Design Rationale
Events are typically generated by event producers and received by event consumers through specific APIs. As systems grow, the number and complexity of events are expected to increase. Today, many systems are integrated not only through conventional API data exchanges but also through real-time events.
This shift highlights the importance of incorporating event design as an integral part of API design, ensuring that systems can effectively handle and respond to dynamic, real-time data streams. By treating events as first-class citizens in API design, developers can create more responsive, scalable, and resilient systems that are better equipped to handle the demands of modern, event-driven architectures.