This document discusses how to prevent APIs from breaking by decoupling clients and servers. It recommends: 1. Programming clients for business capabilities rather than technical API details to reduce dependencies on any single API. 2. Representing capabilities, not internal systems, in APIs to minimize the need for changes. 3. Following best practices like defensive programming, retry policies, and redundancy to make clients more resilient to potential API issues. This approach aims to dramatically reduce codebases, documentation needs, and downtime while increasing API client resilience and competition between providers.

1. LOW-CODE API
APIS THAT DON'T BREAK
SUPERFACE.AI

2. Core member of Apiary
API startup, acquired by Oracle in 2016
Founder of API consulting agency Good API
Helps several Fortune 100 companies with their API strategy
and execution
Founder & CTO of superface.ai
Zdenek “Z” Nemec
SUPERFACE.AI

3. Change is a constant, APIs break
SUPERFACE.AI

6. backend@mycompany.com

7. API versioning comes after a breaking change
SUPERFACE.AI
this talk is not about API versioning

8. Why APIs break?
SUPERFACE.AI

9. Why APIs break?
SUPERFACE.AI
Business
capabilities
Technical
interfaces
APIs
APIs are where business capabilities meet technical interfaces

10. Why APIs break?
SUPERFACE.AI
Business reasons Technical reasons

11. Why APIs break?
SUPERFACE.AI
Business reasons
Technical reasons
• Business strategy
• Business availability
• Business rules change
• Regulations

12. Why APIs break?
SUPERFACE.AI
Business reasons
Technical reasons
• Business strategy
• Business availability
• Business rules change
• Regulations
• API design change
• Optimization
• Deprecation
• Leaking internal changes
• Bugs, regression issues
• Documentation out of sync
• Network issues
• OPS issues

13. What can we do
SUPERFACE.AI
Technical
reasons
to prevent APIs from breaking

14. Decouple client from server
SUPERFACE.AI
tight coupling
• more interdependency
• more coordination
• higher information density
loose coupling
• less interdependency
• less coordination
• lower information density
Technical
reasons
Image credits: https://en.wikipedia.org/wiki/
Coupling_(computer_programming)

15. Decouple client from server
SUPERFACE.AI
Server-side Client-side
Server-side Client-side
Technical
reasons

16. What (else) can we do?
SUPERFACE.AI
• Decouple clients
→ describe your capabilities not
API
• Minimize the need for change
• Don’t do breaking changes
• Decouple from server
→ program for capability not API
• Minimize the need for change
• Play defensive
• Have backup-plan: API
consumption strategy
Server-side Client-side
Technical
reasons

17. How
SUPERFACE.AI
Technical
reasons
to prevent APIs from breaking

18. Decouple client and server
Server-side
Client-side
reduce the touch point between client and server to business logic
Business use-case Technicalities how to call API
Design-time
(programming the client)
Runtime
(running the client)
SUPERFACE.AI
Showcasing solution with superface.ai, other decoupling solutions possible
e.g. using ALPS or hypermedia + vocabularies

19. Decouple client and server
Server-side
Client-side
program client for use-case NOT API
SUPERFACE.AI
NOTHING about API
in client codebase

20. Decouple client and server
Actual API Call
Code executed
API
Runtime: Instructions how to make API Call
Server-side
Client-side
Comlink
Technicalities how to call API
Business use-case
ONE
Universal API client
the whole picture
SUPERFACE.AI

21. TL;DR: Decouple client and server
Describe your capabilities, not APIs Program for capability, not API
Provider Consumer
SUPERFACE.AI

22. SUPERFACE.AI
• Use clean, hexagonal architecture
• Representor pattern
• Do not leak internal systems /
implementation to the API surface
(design)
• Do not depend on API surface in the
client business logic
Minimize the need for change
https://medium.com/idealo-tech-blog/hexagonal-ports-adapters-architecture-e3617bcf00a0
Server-side
Client-side

23. SUPERFACE.AI
1. You MUST NOT take anything away
2. You MUST NOT change processing rules
3. You MUST NOT make optional things required
4. Anything you add MUST be optional
No breaking changes
Rules for extending
Server-side
follow rules for extending
For breaking changes follow selected API versioning strategy or API change
management

24. Defensive client, tolerant reader
Be conservative in what you do, be liberal in what you
accept from others.
– Jon Postel
https://martinfowler.com/bliki/TolerantReader.html
Client-side
SUPERFACE.AI

25. Have backup-plan: API consumption strategy
• Know your dependencies
• Monitor your dependencies
• Have retry policies in place
• Redundancy: fail-over
Client-side
SUPERFACE.AI

26. Outcome
SUPERFACE.AI

27. Low-code: No API code in client
Client-side
SUPERFACE.AI
ONE PER PROVIDER
API–speci
fi
c code
ONE PER USE-CASE
Business-speci
fi
c code
-vs-
❌ BRITTLE INTEGRATION
breaks if API changes, results in vendor lock-in
🟢 RESILIENT TO CHANGES
redundancy, provider selection freedom

28. Low-code: No versions in codebase
SUPERFACE.AI
Server-side
ONE VERSION
Evolve independently, do
not drag the legacy along
EVERY VERSION OF API
Version -speci
fi
c code,
deployments, monitoring,
support, documentation...
-vs-

29. Outcome
SUPERFACE.AI
• Dramatic Code base reduction → min time to market, costs
• Highly resilient API clients → min downtime, maintenance
• Redundancy → backup providers, opening competition
• Documentation reduction → min time, min room for error, costs

30. SUPERFACE.AI
LET’S GET IN TOUCH
I’d like to know what you think!
SUPERFACE.AI
Technical preview available today
@ZDNE
Z@SUPERFACE.AI
TWITTER
EMAIL
THANK YOU!