Applied · Module 2
Integration and APIs
Systems talk in two main ways.
Previously
Architecture styles in the real world
The big styles are patterns, not rules.
This module
Integration and APIs
Systems talk in two main ways.
Next
Quality attributes and trade offs
latency and throughput are easy to measure.
Progress
Mark this module complete when you can explain it without rereading every paragraph.
Why this matters
Service A calls Service B synchronously.
What you will be able to do
- 1 Explain integration and apis in your own words and apply it to a realistic scenario.
- 2 Integration is where systems fail. Make contracts and signals explicit.
- 3 Check the assumption "Contracts are versioned" and explain what changes if it is false.
- 4 Check the assumption "Failures are observable" and explain what changes if it is false.
Before you begin
- Foundations-level vocabulary and concepts
- Confidence with basic diagrams and section terminology
Common ways people get this wrong
- Distributed monolith. Tight coupling across services keeps the complexity and loses the benefits.
- Breaking changes. Unversioned change breaks systems silently.
Main idea at a glance
Integration paths
Synchronous calls and event messaging solve different risks.
Stage 1
Client
Waits for the entire chain to complete before proceeding.
I think synchronous from the client perspective feels simple but creates brittle systems.
Systems talk in two main ways. A synchronous call feels simple but creates tight coupling. An asynchronous message decouples systems but adds coordination work.
Contracts matter. A contract must be versioned so older clients keep working.
Worked example. A retry storm you accidentally built
Worked example. A retry storm you accidentally built
Service A calls Service B synchronously. B gets slow. A times out and retries. Now A generates more traffic precisely when B is weakest. The system collapses under “helpful” retries.
Common mistakes in integration
Integration mistakes to remove
Most integration incidents are predictable when retries, contracts, and idempotency are unclear.
-
Unbounded retries with no jitter
Always cap retries and use jittered backoff to avoid retry storms under dependency stress.
-
Missing idempotency design
Define idempotency keys or safe replay behaviour so duplicates do not corrupt state.
-
No contract versioning
Version APIs and events so consumers can migrate safely without hard cutovers.
Verification. Integration checklist you can run in review
Integration verification checklist
Use this checklist in design and incident-readiness reviews.
-
Control timeout and retry budgets
Ensure timeouts are explicit, retries are bounded, and backoff includes jitter.
-
Confirm idempotent retry paths
Document which operations are safe to replay and how duplicate handling works.
-
Define error semantics clearly
State which errors are retryable and which must fail fast for user safety.
-
Version event schemas
Add schema versioning and a replay strategy before publishing events to shared consumers.
Reflection prompt
Where would you rather pay complexity: in synchronous coupling today, or in asynchronous coordination over time.
Mental model
Integration and APIs
Integration is where systems fail. Make contracts and signals explicit.
-
1
Client
-
2
API
-
3
Contract
-
4
Service
-
5
Signals
Assumptions to keep in mind
- Contracts are versioned. Versioning is how you change safely without breaking consumers.
- Failures are observable. If failures are invisible, incident cost rises and trust falls.
Failure modes to notice
- Distributed monolith. Tight coupling across services keeps the complexity and loses the benefits.
- Breaking changes. Unversioned change breaks systems silently.
Key terms
- synchronous call
- A request where the caller waits for a response.
- asynchronous message
- A message sent without waiting for an immediate response.
- contract
- The agreed structure and behaviour of an API or message.
Check yourself
Quick check. Integration and APIs
0 of 7 opened
Why are synchronous calls risky
They couple services and failures can cascade.
Why use asynchronous messaging
It decouples services and improves resilience.
What is backward compatibility
New versions do not break older clients.
Scenario. Service B is slow and Service A retries aggressively. What failure pattern can you trigger
A retry storm. Retries add load precisely when the dependency is weakest, which can take the whole system down.
Why version an API contract
So change can happen safely.
What is a message queue for
Buffering work when systems are slow or down.
What should an API contract always define
Inputs, outputs, and error behaviour.
Artefact and reflection
Artefact
A one-page decision note with assumption, evidence, and chosen action
Reflection
Where in your work would explain integration and apis in your own words and apply it to a realistic scenario. change a decision, and what evidence would make you trust that change?
Optional practice
Compare synchronous calls with asynchronous messages and see the trade offs.