Spring Cloud Contracts Pact Spring ecosystem, java-based contracts. YAML DSL Their integration

1. Consumer Driven Contracts
in Java world

2. About myself
● Application Architect @Thomas
Cook
● Tech Lead - Platformers team
● +9 years Java

3. Content
● Consumer Driven Contracts - general concepts;
● Consumer Driven Contracts - hygiene for APIs;
● Spring Cloud Contracts;
● Pact;
● Demo.

4. Monolith: Past expectation

5. Monolith: Today’s Reality

6. Conclusion...

7. We need microservices!!!

8. They will be small and tidy

9. Well, yes, but....

10. And in a year we will see something like:

11. Conclusion...

12. Microservices require
more attention to
standards

13. Will your cool, modern microservices bring any
value in terms of time-to-market...

14. Will your cool, modern microservices bring any
value in terms of time-to-market...
...without agreements/contracts between them?

15. In terms of Quality Attributes:
It’s never enough to comply with Runtime
attributes
when your Design attributes are not in order.

16. We started with API Documentation at the
time of decomposing our monolith

17. But as time goes by we have come to realize
it’s not enough...

18. Because our
documented API
looks more like this:

19. And our expectation was a system where
services know about each other

20. Standards are required for things like monitoring,
logging, backward compatibility, and API contracts.
API Contracts

21. Lean principle:
A service is of value to the business only to the
extent it is consumed.
https://martinfowler.com/articles/consumerDrivenContracts.html

22. Make sure the Contracts can be imposed
Set of rules and
technologies that should be
implemented and adopted
on both sides.

23. Do it as early as you can!

24. Option 1: testing a chain of services without
contracts

25. You can go the hard way and deploy all
microservices at once to test them
together

26. Drawbacks:
● Long cycle;
● Full Infrastructure required;
● Hard to debug;
● Very late feedback;

27. Option 2: Mock other microservices in unit /
integration tests

28. Drawbacks:
● It simple has nothing to do with
the reality if you do it in isolation.

29. Postel's law
“Be conservative in what you do, be liberal in
what you accept from others
(often reworded as "Be conservative in what you
send, be liberal in what you accept").”

30. Doesn’t Contract couple our services?

31. Enter Consumer Driven Contracts

32. Producer should have a contract for every
specific Consumer

33. It means that potentially there can be multiple
contracts, a separate one for each Consumer,

34. Contract visualisation:
API:
get: customers/{id}
post: customers/
put: customers/{id}
delete: customers/{id}
get: customers/{id}/bookings/{id}
post: customers/{id}/bookings/
delete: customers/{id}/bookings/{id}Producer

35. API:
get: customers/{id}
post: customers/
put: customers/{id}
delete: customers/{id}
get: customers/{id}/bookings/{id}
post: customers/{id}/bookings/
delete: customers/{id}/bookings/{id}
Consumer 1
Producer
get: customers/{id}
post: customers/
put: customers/{id}
Contract visualisation:

36. API:
get: customers/{id}
post: customers/
put: customers/{id}
delete: customers/{id}
get: customers/{id}/bookings/{id}
post: customers/{id}/bookings/
delete: customers/{id}/bookings/{id}
Consumer 1
Producer
Consumer 2
get: customers/{id}
post: customers/
put: customers/{id}
put: customers/{id}
delete: customers/{id}
Contract visualisation:

37. API:
get: customers/{id}
post: customers/
put: customers/{id}
delete: customers/{id}
get: customers/{id}/bookings/{id}
post: customers/{id}/bookings/
delete: customers/{id}/bookings/{id}
Consumer 1
Producer
Consumer 2
get: customers/{id}
post: customers/
put: customers/{id}
put: customers/{id}
delete: customers/{id}
Consumer 3
get: customers/
{id}/bookings/{id}
post: customers/{id}/
bookings/
Contract visualisation:

38. API:
get: customers/{id}
post: customers/
put: customers/{id}
delete: customers/{id}
get: customers/{id}/bookings/{id}
post: customers/{id}/bookings/
delete: customers/{id}/bookings/{id}
Consumer 1
Producer
Consumer 2
get: customers/{id}
post: customers/
put: customers/{id}
put: customers/{id}
delete: customers/{id}
Consumer 3
get: customers/
{id}/bookings/{id}
post: customers/{id}/
bookings/
Overlapping part of 2 contracts
Contract visualisation:

39. API:
get: customers/{id}
post: customers/
put: customers/{id}
delete: customers/{id}
get:
customers/{id}/bookings/{id}
post:
customers/{id}/bookings/
Consumer 1
Producer
Consumer 2
get: customers/{id}
post: customers/
put: customers/{id}
put: customers/{id}
delete: customers/{id}
Consumer 3
get: customers/
{id}/bookings/{id}
post: customers/{id}/
bookings/
Overlapping part of 2 contracts
Completely independent contract
delete: customers/{id}/bookings/{id}
Contract visualisation:

40. API:
get: customers/{id}
post: customers/
put: customers/{id}
delete: customers/{id}
get:
customers/{id}/bookings/{id}
post:
customers/{id}/bookings/
Consumer 1
Producer
Consumer 2
get: customers/{id}
post: customers/
put: customers/{id}
put: customers/{id}
delete: customers/{id}
Consumer 3
get: customers/
{id}/bookings/{id}
post: customers/{id}/
bookings/
Overlapping part of 2 contracts
Completely independent contract
delete:
customers/{id}/bookings/{id}
No in use
Contract visualisation:

41. Some parts of the APIs might not be used and
will not impact anyone. They might either be in a
state of active development or about to be
decommissioned

42. Demystification
These tests are not component tests. They do not
test the behaviour of the service deeply but that
the inputs and outputs of service calls contain
required attributes.

43. Contract: specific scenario rather than schema
Their main advantage is that they are fast and
reliable.

44. What tools are there for Java devs?

45. There are 2 main options:
1. Spring Cloud Contracts;
2. Pact.

46. Spring Cloud Contracts
● Spring Cloud Contract Verifier - the
producer side;
● Spring Cloud Contract Stub Runner - the
consumer side

47. Spring Cloud Contracts: Contract Verifier
Shipped with Contract Definition Language
(DSL) written in Groovy or YAML.

48. Spring Cloud Contract Verifier provides:
● Alignment between stubs and actual
implementation;
● Acceptance test driven development;
● Immediate visibility of contracts on both sides;
● Autogenerated boilerplate tests.

49. Spring Cloud Contracts: Contract Stub Runner
● Fetches the stubs of the producer;
● Runs tests against the stubs.

50. Spring Cloud Contracts: Contract Definition
Language

51. There’s more if you read into specs:
● Groovy DSL
● YAML
Spring Cloud Contracts: Contract Definition
Language

52. There’s more if you read into specs:
● Groovy DSL
● YAML
● Pact JSON
● Spring Rest Docs
Spring Cloud Contracts: Contract Definition
Language

53. Spring Cloud Contracts - catchline
“Spring Cloud Contract Verifier moves TDD to
the level of software architecture.”

54. SCC guarantees:
● Stubs reliability: generated on successful test
execution.
● Stubs reusability: packed in a separate artifact
with a stub classifier.

55. Spring Cloud Contract: look inside

56. Server / Producer side utilization:
Maven/gradle plugin + verifier

57. Server / Producer side: contract DSL
Groovy YAML
package contracts
import org.springframework...t
Contract.make {
request {
method 'PUT'
url '/bookings/4'
body("""
{
"id": 4,
"destination": "USA",
….
}
response {
status 204
request:
method: PUT
url: /bookings/4
body:
id: 4,
destination: "USA"
response:
status: 204

58. Server / Producer side: base class
<baseClassForTests>....api.controllers.BookingControllerImplTest</...>

59. Server / Producer side: base class
The responsibility to initialising your MockMvc is on you:
java.lang.IllegalStateException: You haven't configured a MockMVC
instance. You can do this statically
RestAssuredMockMvc.mockMvc(..)
RestAssuredMockMvc.standaloneSetup(..);
RestAssuredMockMvc.webAppContextSetup(..);
or using the DSL:
given().
mockMvc(..). ..

60. Server / Producer side: producer stubs
Spring Cloud Contract Verifier will convert the contracts into an HTTP
server stub definitions(Wiremock mapping jsons).

61. Demo time!
● Run Producer tests;
● Spring-cloud-contract-maven-plugin options;
● Run Consumer tests;
● Groovy DSL vs YAML;
● Add stateful behaviour(real MySql instance) for visibility;
● Non-binary storage(git);
● Explain stubrunner yaml property and how it impacts tests;
● Wiremock scenarios;
● produce(), consume() and matchers;
● execute() with custom utility methods;
● Integration with the rest of Spring Cloud.

62. Pact
The cross-language distributed
contract testing framework.

63. Pact: language support
● Ruby Pact
● JVM Pact and Scala-Pact
● .NET Pact
● JS Pact
● Go Pact (there is also a v1.1 native Pact Go)
● Swift / Objective-C Pact
● Python
● PHP

64. Pact: objective
The requirements of the consumer(s)
are used to drive the features of the
provider.

65. Pact: diagram
Consumer
● Specifies the contracts;
● Generates the pact files;
● Push them into Pact Broker

66. Pact: diagram
Consumer
● Specifies the contracts;
● Generates the pact files;
● Push them into Pact Broker
Pact Broker
● Stores pact contracts;
● Integrates into CI tools.

67. Pact: diagram
Consumer
● Specifies the contracts;
● Generates the pact files;
● Push them into Pact Broker
Pact Broker
● Stores pact contracts;
● Integrates into CI tools.
Producer
● Implement a service
according to Consumer
specs.

68. Demo time!
● Pact core concepts: State, Broker, Verification;
● Versioning;
● Pact extension for Spring Cloud Contracts;

69. Useful links
● https://github.com/spring-cloud-samples/spring-cloud-contract-samples
● https://github.com/DiUS/pact-workshop-jvm
● https://github.com/DiUS/pact-jvm
● https://github.com/DiUS/pact-jvm/tree/master/pact-jvm-provider-maven

70. Summary
Use API Contracts ?: Adopt a design first approach ?: Document
your APIs ?: You are hopeless

71. Thank you!
Mail: yura.v.nosenko@gmail.com
Linkedin: https://www.linkedin.com/in/yuranos/
Github example:
https://github.com/yuranos/raml-based-producer-application,
https://github.com/yuranos/raml-based-consumer-application
(consumer_driven_contracts branches)