This document discusses coordinating APIs between producer and consumer applications using Spring Cloud Contract (SCC). It begins with an example of how separate development of APIs by each team can lead to misaligned implementations. It then demonstrates how SCC allows teams to define API contracts, generate test stubs, and validate implementations without copying contracts or requiring early integration. The key benefits of SCC are that it establishes contract artifacts, enables consumer-driven API design, and provides two-way validation of implementations against a shared contract. Various SCC workflows and uses of contract repositories are also outlined.

1. Coordinating APIs with Spring
Cloud Contract

2. omri.spector@develeap.com
About me
• Omri Spector, CTO deveLeap
• deveLeap mission
– Helping development teams use the right tools,
technologies & architecture to achieve their business
objective.
– Specialize in Java, DevOPS and the JVM eco-system
• Omri
– Active commercial developer since 1985
– In Java since 2004
– Managed large multi national development groups

3. omri.spector@develeap.com
Agenda
• Introduction
– The challenge
– CDC Answer
• Demo – Spring Cloud Contract
• Wrap up - workflows

4. Lets start with a bedtime story

5. omri.spector@develeap.com
PM Has a new and exciting feature

6. omri.spector@develeap.com
Two teams are involved
Producer (“Server”) Consumer(“Client”)

7. omri.spector@develeap.com
So they discuss the feature
(And the API. Sort of.)

8. omri.spector@develeap.com
Each writes their own end

9. omri.spector@develeap.com
They even write tests

10. omri.spector@develeap.com
And all is green

11. omri.spector@develeap.com
Deploy to real environment

12. omri.spector@develeap.com

13. omri.spector@develeap.com
What Happened?
• Each side had a “copy” of the contract
• Each side wrote it’s own tests, so it was always
green
• But in reality…
– Different URL, Different queue
– Different structure
– Different data type
– Different headers
– :

14. omri.spector@develeap.com
Why are we talking with ghosts?
• Because you can’t wait for the other team
• Because you can’t start the whole damn
system all the time
• Because it is hard to find issues with all the
system up

15. omri.spector@develeap.com
But what if we wrote WSDL?
• AND we did NOT copy it, of course
• API Schemas come with another set of
challenges:
– Strict beyond need of specific customer
– Server owned by definition
• Who said server team is available?
• How do we get them to write a nice API?

16. omri.spector@develeap.com
And this gets worse over time
• Server needs to evolve, and so do the server
APIs – are we maintaining the contract?
• When can we drop an API? A field?
• Can we fix a typo?
• And what happens if we change a header?
Encoding?

17. omri.spector@develeap.com
Enter Micro-Services
• A whole new world of trouble:
– Many producer-consumer pairs
– Complex environment to spin
– The service breaking the
contract, is not the one
that fails

18. omri.spector@develeap.com
So Our Challenge Is
• We don’t want to require E2E testing as the
basic validation
• We must avoid multiple copies of contract
• We suffer when tests & stubs are written
together hiding real integration
• We want to avoid strict contracts that limit the
server and impose un-needed detail on the
client

19. In graphic form the problem is
actually very clear

20. omri.spector@develeap.com
Integration Use Case
Consumer Producer
Controller logic Controller logic

21. omri.spector@develeap.com
Unit Testing is not Enough
Consumer Producer
Controller logic Controller logic
Unit
Test
Stub
Unit
Test Stub
NOT
ALIGNED

22. omri.spector@develeap.com
SCC To The Rescue
Consumer Producer
Controller logic Controller logic
Unit
Test
Stub
Unit
Test Stub
Artifact Repo
Contract
Generate Generate

23. Demonstration
Stop talking. Start Doing.
Sources of demonstration on GitHub:
Producer - https://github.com/ospector/jj2017-scc-producer
Consumer - https://github.com/ospector/jj2017-scc-consumer

24. omri.spector@develeap.com
The Benefits of SCC
• Contracts as artifact
– Versioned with the product
– Shared, re-usable
• Stub validity
– Server verified to stick to contracts
– Client receives updates if server changes
• Enables Consumer-oriented, lean API design

25. omri.spector@develeap.com
Consumer Driven Contracts
• Ownership:
– Contracts are owned by their consumers
– Contracts relate to the part that interests the
consumer, not to the whole API
– APIs are owned by producers, but subject to contracts
• Versioning
– Contracts relate directly to producer version
• Validation:
– Contracts are checked as part of every build
– Contracts generate both stubs and tests
– Checks are two way, based on a single contract

26. omri.spector@develeap.com
An SCC CDC Workflow
Consumer
• Clones producer
• In own code - TDDs feature
• In producer code - Writes contract
• Rinse & repeat until happy with contract
• PR
• Move to repo based stubs
Producer
• Takes over PR
• Implements API (not necessarily logic)
• Merge & release

27. omri.spector@develeap.com
Contract Repository
• In some cases we may prefer to put all
contracts in a third repository
– Centralizes all contracts in a system
– “Protects” code from other teams

28. omri.spector@develeap.com
Standalone Stubs
• SCC can also run stubs as a standalone
application
• This is good for:
– Non-Java clients
– Smoke testing End-to-end

29. Thank you!
www.develeap.com
Contact: omri.spector@develeap.com