This document discusses contract-driven API design using Swagger and Pact. It introduces Swagger for defining provider contracts by specifying API endpoints and parameters. It then discusses using Pact for consumer-driven contracts, where consumers define expectations of responses from providers. It provides examples of defining pacts between a mapping service consumer and datastandard provider. It also demonstrates validating pacts by testing provider implementations meet consumer expectations.
5. 5.
APIs in a Microservice architecture
Unstable / changingAPIs
No type safety between services
No developer confidence
6. 2
Provider contracts
- with Swagger
“ A Provider Contract is a
description of a service offered by a
provider”
- Steven Smith
https://dzone.com/articles/application-pattern-consumer
7. 7.
Swagger Example The Petstore
paths:
'/pet/’:
post:
tags:
- pet
description: Add a new pet to the store
consumes:
- application/json
produces:
- application/json
parameters:
- in: body
name: body
description:Pet object that needs to be added to the store
required:true
schema:
$ref: '#/definitions/Pet‘
responses:
'405':
description:Invalid input
'200':
description:successful operation
'/pet/{petId}':
get:
tags:
- pet
summary:Find pet by ID
produces:
- application/json
parameters:
- name: petId
in: path
description:ID of pet to return
required:true
type: integer
responses:
'200':
description:successful operation
schema:
$ref: '#/definitions/Pet'
'404':
description:Pet not found
security:
- api_key: []
8. 8.
Why define service endpoints?
API that are JSON first
Documentation and clarity
Server / Client code generation
9. 9.
Iterative API first development
Update
Swagger
Definition
Generate
Endpoints
Implement
functionality
Test and
validate API
New demands
for API
11. 3
Consumer-Driven contracts
- with Pact
“ A Consumer Driven Contract is a
description of how a provider satisfies an
aggregate of Consumer Contracts ”
- Steven Smith
https://dzone.com/articles/application-pattern-consumer
12. 12.
Integration test in a Microservice architecture
Characteristic
Slow
Easy to break
Hard to fix
Scales BADLY
Lots of infrastructure
Lots of set up
False negatives
Infrastructure
Startup all services
Populate Databases
Mock away external
services
http://www.slideshare.net/bethesque/pact-44565612
13. 13.
Pact tests
Characteristic
Fast
Stable
Easy to debug
Reliable
No extra infrastructure
Low setup
Scales linearly
Contracts for only the needed stuff
Consumer-driven contracts describes the complete set of functionality
demanded by the current set of consumers.
http://www.slideshare.net/bethesque/pact-44565612
22. 22.
Problems that can be detected with Pact
Change of the endpoint URL
Change in the expected parameters
Change in the response payload
23. 23.
What is it not good for?
Performance and load testing.
Functional testing of the provider
Should be done by provider's own tests
Pact is about checking the contents and
format of requests and responses.
In this talk we look at using Swagger and Pact to handle REST API specifications and contracts. Swagger allows for a JSON first specification of the API as well as generating and discovering service controllers. This can be done coherently across multiple technology stacks. We will look into using Pact to create consumer driven contract between services in a micro service architecture to improve development confidence.
Different consumers of services -> JSON / XML
Ever evolving microservices we need to change the API
Problem senario
1. Provider service is being updated to a new version
2. It is behaving perfectly
3. But suddenly a number of other services start behaving incorrectly
JSON FIRST: Not just what ever the given framework produces at a given time
CODE GEN:
Server
- Java
- C#
- C
- Ruby
- Node
- PHP
Client
- Android
- Java
- Dart
- Perl
- Akka scala
- Swift
- Ruby
1. The consumer defines what it expects from a specific request to a service
2. The provider and the consumer agree on this contract
3. The provider continuously verifies that the contract is fulfilled
E.g. renamed endpoints
E.g. new mandatory fields
Returns an array, instead of having an array wrapped in an object
Clearly API-breaking changes. May not be obvious that a code change changes the API.
- Renamed Class / Field that are later JSON serialized
It may also not be clear which Consumers are affected by code changes.