Standard for API-Driven and Event-Driven Application Communication

Metadata	Value
Source	Confluence - Standard for API-Driven and Event-Driven Application Communication
Status	Published
Last Synced	2026-01-08
Space	Architecture (ARCH)

1. Executive Summary

As part of Planet's ongoing technology modernisation, this standard establishes APIs and event-driven architecture as the foundation for application communication. By phasing out legacy communication methods such as direct database writes, file transfers, and change data capture (CDC), we aim to enhance scalability, resilience, and operational efficiency.

Legacy approaches, while effective in the past, now present significant challenges - including high maintenance costs, limited automation, and increased system fragility. APIs and events offer a modern alternative, improving system decoupling, observability, and testability while reducing long-term cost-to-run.

This standard applies to new development and system updates, with exceptions only in cases where business-critical factors (e.g., timelines) justify the trade-off. Non-compliant systems will be classified as technical debt, and teams will be supported in transitioning to more scalable solutions.

2. Purpose

This standard aims to contribute to enhanced design when deciding how applications should communicate. The goal is not to question existing systems or revisit past decisions, but to establish:

APIs and Events as the foundation for application communication to enhance scalability, resilience, and testability
Modernise the technology stack by phasing out anti-patterns that hinder automation and maintainability
Reduce long-term operational costs by transitioning to scalable, efficient communication mechanisms

3. Scope

Strongly recommended for all new applications and updates to existing systems
Applies to internal and external integrations (unless external dependency contracts specify otherwise)
Legacy systems not adhering to this standard will be included in the technical debt registry

4. Communication Mechanisms

This standard advocates the following mechanisms as the patterns for application communication:

Aspect	API-Driven	Event-Driven
Definition	Enable communication between different software systems through defined endpoints and protocols. These interfaces allow applications to request and exchange data in a standardised and secure manner.	Enable asynchronous communication by emitting events when significant actions occur, allowing other systems to react and process them in real-time or as background processing.
Technology Examples	REST, GraphQL (Mutations and Queries), gRPC	Kafka, RabbitMQ
Features	• Authentication and authorisation for security<br>• Versioning for decoupled evolution<br>• Easily mockable for automated testing<br>• Well-known resilience patterns (timeouts, fallbacks, circuit breakers)<br>• Enable Contract-first development	• Decoupling of producers and consumers<br>• Easily mockable for automated testing<br>• Event replay for resilience<br>• Same event serves multiple purposes (e.g., Data Platform)<br>• Enable Contract-first development
Use Cases	Synchronous interactions and service integrations (can support long-running operations with async patterns)	Real-time updates, event-driven processes, and decoupled workflows

4.1. Decision Tree: APIs vs Events

Deciding between APIs and Events is complex. Key considerations:

Factor	Favour APIs	Favour Events
Communication Style	Need immediate response	Fire-and-forget acceptable
Coupling	Tight coupling acceptable	Loose coupling required
Data Consistency	Strong consistency needed	Eventual consistency acceptable
Consumer Knowledge	Known consumers	Unknown/multiple consumers
Throughput	Low to medium	High throughput required
Failure Handling	Immediate error handling	Retry/replay needed

4.2. Important Considerations

Idempotency of Consumers
- Consumers of both APIs and events MUST be designed to be idempotent
- Processing the same message multiple times must not result in unintended side effects
- Critical when events are retried or API calls are repeated due to network issues
Database Integrity and Systems Operators Interference
- Direct database changes outside the event-driven or API flow can disrupt data consistency
- Application owners should design operational tools (e.g., single or batch event replays)
API and Event Ordering
- Order in which actions occur can be critical
- Ensure requests or events are processed in the correct sequence for system consistency
- Especially important in state transition systems
Eventual Consistency
- Event-driven systems naturally promote eventual consistency
- APIs should be designed with this consideration as well
- Handle cases where data may not be immediately consistent across systems
Observability and Error Handling
- Proper monitoring and error-handling mechanisms are essential
- APIs: track request statuses, retries, response handling
- Events: monitor delivery, processing, and log failures
- Both require robust systems for retries, alerts, and tracing
Security and Authentication
- Both APIs and events MUST incorporate strong security practices
- Include authentication, authorisation, and data encryption
- Protect sensitive information and prevent unauthorised system access
Versioning
- Versioning APIs and Events allows for decoupled evolution
- New versions should follow a deprecation notice for consumers to adapt
- Supporting outdated APIs/Events often causes inability to clean obsolete logic

5. Benefits

Perspective	Benefits
📈 Scalability	Systems grow independently without tight coupling; can handle concurrency and load distribution efficiently
Extensibility	Systems evolve more easily with greater flexibility and less impact on existing components
💪 Resilience	Asynchronous communication reduces cascading failures; API-Driven enables well-known resilience strategies
🧪 Testability	Automated testing of APIs and Events ensures faster, more reliable releases; enables mocking and contract testing
👩‍💻 Developer Productivity	Streamlined integration, debugging, and Contract-first approach for added productivity
👀 Operational Visibility	Better monitoring and diagnostics for compliance and reliability
💰 Cost Efficiency	Lower maintenance and operational costs by reducing manual testing, debugging, and error handling
💸 Cost-to-run	APIs and Events support efficient resource utilisation, reduce dependency on legacy infrastructure

6. Anti-Patterns

The following legacy communication practices are considered anti-patterns that should be minimised:

Change Data Capture (CDC)

Aspect	Details
Current Practice	Applications read changes directly from a database, using tools like Debezium or Fivetran
Issues	• Tight coupling between databases<br>• Schema changes can break downstream systems<br>• Hard to automate testing (full environment needed)<br>• Costly to test manually
Cost Impact	Higher infrastructure costs due to tightly coupled systems and redundant processing
Preferred Alternative	Use event-driven systems for updates and domain events for decoupling

File Transfers

Aspect	Details
Current Practice	Applications exchange data via files over FTP or shared directories
Issues	• High latency and poor real-time support<br>• Complex error handling and limited monitoring<br>• Difficult to automate testing<br>• Batch processing harms observability<br>• Scaling requires infrastructure growth
Cost Impact	Increased storage and compute costs from batch processing; higher infrastructure costs for file management
Preferred Alternative	APIs with structured payloads or event streams - going from batch to single processing if possible

Direct Database Writes

Aspect	Details
Current Practice	Applications write directly into another application's database
Issues	• Tight coupling between systems<br>• Breaks encapsulation and modularity<br>• High risk of data corruption and inconsistency<br>• Almost impossible to automate testing<br>• Bypasses target system validations and security<br>• Lack of transparency and auditing<br>• Hard to add new business logic
Cost Impact	Inefficient resource use from complex synchronisation and higher failure rates
Preferred Alternative	Use APIs for data exchange or service calls to enforce clear boundaries

7. Moving Forward

This standard should be followed in new solutions or updates to existing ones.

Key Points

🛠️ Non-compliant systems will be classified as technical debt
⚠️ Continued use of anti-patterns will hinder innovation and expose systems to operational risks
💸 Teams using legacy practices may face increased cost-to-run due to inefficiencies

7.1. Strategies

Launch tech-oriented initiatives to pay down technical debt
- Eliminate anti-patterns in favour of standard strategies
- Build business cases considering costs of downsides vs benefits of standard approaches
- Architecture team can help collect data and build business cases
Dilute the cost of technical debt in business initiatives
- Slightly harms time-to-market but allows slow movement in the right direction
- Benefits will start paying off the effort over time

8. Frequently Asked Questions

Code	Question	Answer
FAQ.1	Why can't we keep using existing practices if they work today?	Legacy practices like FTP and direct database writes increase fragility, hinder scalability, and delay business operations, leading to higher costs, slower time to market, and limited automation.
FAQ.2	How does this improve testing?	APIs and Events are inherently more testable. They allow mocking, replaying, and integration into automated CI/CD pipelines, unlike anti-patterns which require heavy manual testing.
FAQ.3	What happens to existing systems that don't comply?	Existing systems will be classified as technical debt and require a roadmap for remediation over time.
FAQ.4	Isn't it costly to replace legacy practices?	Although the initial investment may be higher, the long-term benefits—such as better scalability, improved reliability, and lower manual testing costs—make it well worth the effort.
FAQ.5	Can exceptions be made for certain legacy systems?	Exceptions may be considered on a case-by-case basis but must be documented with an action plan for future compliance.