Applied Digitalisation · Module 3
APIs and system integration
APIs are the contracts that keep systems aligned.
Previously
Analytics, AI, and control loops
Collecting data is the easy part.
This module
APIs and system integration
APIs are the contracts that keep systems aligned.
Next
Data models and mapping
A shared data model keeps systems aligned.
Progress
Mark this module complete when you can explain it without rereading every paragraph.
Why this matters
A team adds a new required field to an API request because “we need it now”.
What you will be able to do
- 1 Explain apis and system integration in your own words and apply it to a realistic scenario.
- 2 Integration works when contracts are clear and behaviour is observable.
- 3 Check the assumption "Contracts are stable" and explain what changes if it is false.
- 4 Check the assumption "Failures are visible" 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
- Integration sprawl. Point-to-point growth creates fragile dependencies.
- Unversioned change. Changes without versioning break consumers silently.
Main idea at a glance
Integration view
Contracts keep services stable as they evolve.
Stage 1
Service A
The service that produces data or capability. It publishes an API with a defined schema, response format, and availability SLA. The publisher is responsible for the contract being accurate and stable.
Without these controls, integration is just two services hoping for the best.
APIs are the contracts that keep systems aligned. A webhook supports real time updates without constant polling.
When integrations are vague, every team invents their own definition and version. The result is slow change and fragile services.
Worked example. A breaking change that nobody meant to ship
Worked example. A breaking change that nobody meant to ship
A team adds a new required field to an API request because “we need it now”. In their service, it works. Downstream, consumers fail, retries spike, and suddenly your “integration” is a denial of service against yourself.
Common mistakes in integration
Integration anti-patterns
Prevent these design errors before exposing interfaces.
-
Treating APIs as internal functions
External consumers need contractual stability and explicit compatibility rules.
-
Skipping versioning strategy
Unmanaged change turns minor edits into downstream outages.
-
Leaving error semantics undefined
Consumers will guess retry behaviour and create brittle loops.
-
Ignoring idempotency
Retries can create duplicates and corrupt state without idempotent handling.
Verification. A minimal contract quality bar
Contract quality bar
Confirm these controls before promoting an API.
-
Explicit versioning and deprecation policy
Set compatibility windows and communicate retirement timelines.
-
Stable identifiers and idempotency
Ensure retried requests cannot create duplicate outcomes.
-
Actionable error semantics
Provide error codes and response bodies consumers can handle safely.
-
Realistic example payloads
Publish examples matching production behaviour, not optimistic assumptions.
Reflection prompt
If you had to support this API for five years, what is the one change you would be scared to make. That fear is telling you what you should design properly now.
Mental model
API and integration boundary
Integration works when contracts are clear and behaviour is observable.
-
1
Producer
-
2
API contract
-
3
Consumer
-
4
Signals
Assumptions to keep in mind
- Contracts are stable. Stability enables reuse and reduces coordination cost.
- Failures are visible. If integration failures are invisible, incidents are slow and expensive.
Failure modes to notice
- Integration sprawl. Point-to-point growth creates fragile dependencies.
- Unversioned change. Changes without versioning break consumers silently.
Key terms
- webhook
- A call a system sends to another system when an event happens.
Check yourself
Quick check. APIs and integration
0 of 7 opened
Why do API contracts matter
They keep services consistent and safe as they evolve.
What does a webhook do
It sends an event to another system when something changes.
Why is versioning important
It prevents breaking changes for consumers and gives teams a safe upgrade path.
What is one job of an API gateway
Auth, throttling, and consistent access control for shared endpoints.
Scenario. A team adds a new required field and calls it a small change. Downstream breaks. What contract rule was missing
A backwards compatibility rule and a versioning policy with a deprecation window. New required fields are breaking changes unless introduced safely.
What makes integrations fragile over time
Hidden assumptions and unclear error semantics, which forces consumers to guess.
Why define error responses
So consumers can handle failures predictably and avoid brittle retry loops.
Artefact and reflection
Artefact
A one-page decision note with assumption, evidence, and chosen action
Reflection
Where in your work would explain apis and system integration 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
Review a contract and check if it is ready for real integrations.