This document discusses contract-driven development using Spring Cloud Contract. It describes how writing contracts upfront to define API behavior can validate that services match expected behavior. The contracts can then be bundled and shared as artifacts that allow clients to test against before integration. This approach aims to address issues like poorly defined APIs, very serial development, and breaking changes by formalizing expectations and enabling collaboration. The document provides an example YAML contract and demos generating test stubs and documentation from contracts. It argues this process can improve communication, catch issues earlier, and allow parallel development.

1. COLLABORATIVE CONTRACT
DRIVEN DEVELOPMENT
BILLY KORANDO - @BILLYKORANDO
DEVELOPER ADVOCATE - IBM

2. ARM YOU WITH KNOWLEDGE OF THE
PROBLEM AND SOLUTION

3. DECONSTRUCTING THE STATUS QUO
(i.e. WHY DEVELOPMENT IS DIFFICULT WITHOUT
CONTRACTS)

4. ASSUME GOOD FAITH BY ALL PARTIES

5. POORLY DEFINED SERVICES

6. SCENE BREAKDOWN
● Poorly defined or undocumented API
● Inconsistent behavior or patterns
● Testing against a live service can give inconsistent results

7. VERY SERIAL DEVELOPMENT

8. SCENE BREAKDOWN
● Inability to utilize resources (i.e. developers) in parallel
● Timeline impacted by any delays from both service and client developers
● Client developer will have to get back up to speed

9. I AM ALTERING THE API

10. SCENE BREAKDOWN
● Breaking API changes not caught until production
● API design governed almost entirely by service developer

11. CONTRACT DRIVEN DEVELOPMENT EXPLAINED
USING SPRING CLOUD CONTRACT

12. SPRING CLOUD CONTRACT
● Very active project
● Inter-operable with other tools/standards: OpenAPI, Packt
● Flexible documentation support with Spring REST Docs
● Polyglot support
More: https://spring.io/projects/spring-cloud-contract

13. WRITING THE CONTRACT
Contract.make {
label “Add New Person”
request {
method 'POST'
url '/api/persons'
body([ fName: “John”
lName: “Doe”])
headers {
header(HttpHeaders.CONTENT_TYPE,
MediaType.APPLICATION_JSON_UTF8_VALUE)}
} response {
status 201
headers {
header(HttpHeaders.LOCATION, 'api/persons/1')}
}
}

14. VALIDATING THE CONTRACT
✅
Add
New
Person
Service

15. SHARING THE CONTRACT
Stubs
Artifact

16. SHARING CONTRACT
Artifact
RepositoryStubs
Artifact

17. VALIDATING AGAINST THE CONTRACT
Stubs
Artifact
Client✅

18. DOCUMENTING THE API

19. CONTRACT DRIVEN DEVELOPMENT IN REVIEW
1. Write contract(s) to define API behavior
2. Contracts validate API matches behavior
3. Bundle contracts as sharable artifact
4. Clients can test/develop against artifact
5. Generate documentation from contracts
}Automated

20. DEMO TIME!

22. PRODUCER DRIVEN CONTRACTS
THE API
WILL LOOK
LIKE THIS
OK
SERVICE CLIENT

23. CONSUMER DRIVEN CONTRACTS
OK
I NEED THIS
FROM THE
SERVICE
SERVICE CLIENT

24. CAN’T SPELL “COLLABORATIVE” WITHOUT
“POLYGLOT”

25. LANGUAGE INDEPENDENT TOOLS
Javascript Developers
JDK
Maven
Java friendly IDE
Docker
Text editor
Java Developers
JDK
Maven
Java friendly IDE
Docker
Text editor
Other Developers
JDK
Maven
Java friendly IDE
Docker
Text editor
✅
✅
✅
✅
✅
❌
❌
❌
✅
✅
❌
❌
❌
✅
✅

26. YAML CONTRACT
request:
label: “Add New Person”
method: POST
url: /api/persons
body:
fName: “John”
lName: “Doe”
headers:
Content-Type: application/json
response:
status: 201
headers:
Location: api/persons/1

27. Client✅

28. DEMO PART DEUX

29. POORLY DEFINED SERVICES

30. SCENE BREAKDOWN
● API is documented as a result of the process
● Documentation is based on contracts which are checked every build
● Clients can develop/test against contracts which give consistent results

31. VERY SERIAL DEVELOPMENT

32. SCENE BREAKDOWN
● Client and service developers can work in parallel once contract is written
● Process encourages discussion on API design

33. I AM ALTERING THE API

34. SCENE BREAKDOWN
● API is checked as part of build process
● Changes will cause either service or client to fail
● Parties informed of changes before hitting PROD and changes become “finalized”

35. Q & A

36. SOURCES
Slides:
Code: https://github.com/wkorando/collaborative-contract-driven-development
https://cloud.spring.io/spring-cloud-contract/single/spring-cloud-contract.html
https://spring.io/blog/2018/02/13/spring-cloud-contract-in-a-polyglot-world