Contract driven development
Download as PPTX, PDF0 likes194 views
This document discusses using an API contract to facilitate collaboration between development teams working on different parts of an application. An API contract in a standard format like OpenAPI/Swagger defines the API in a way that is understandable by both client and server teams. This allows teams to work independently as long as they design to the contract. The contract can be versioned to detect changes. The document outlines how to generate code from the contract, test for breaking changes, and use the contract as a model to generate server and client code stubs.
Contract driven development
- 2. GAP BETWEEN PRODUCER AND CONSUMERS ▪ No way to sync them ▪ Have to code two mechanically matching versions ▪ Changes on one side or the other may lead to errors that will only be exposed with live interactions
- 3. PROBLEM – CLIENT/SERVER TEAMS DEPEND ON EACH OTHER ▪ No standard format to describe API ▪ Client team needed functioning server to do most of their work ▪ Had to spin up full application to get data integration ▪ Changes that were not communicated, leading to bugs ▪ Maintaining separate versions was cumbersome ▪ In monolith, division is between UI and server, but once you get into microservice world, it is among all services that call each other
- 4. API CONTRACT ▪ Agreed upon standard language understandable by teams and ▪ Teams could work independently, as long as they design to the contract ▪ Can create stubs based on the contract with whatever behavior you want ▪ Server ▪ Client ▪ Contract can be explicitly versioned ▪ Easy to compare the versions of the contract to detect changes and communicate differences
- 5. OPEN API/SWAGGER (HTTPS://SWAGGER.IO/) ▪ Industry standard language for describing APIs ▪ JSON or YAML dialects ▪ Tool ecosystem ▪ Swagger editor (https://editor.swagger.io) ▪ Restlet studio (https://studio.restlet.com) ▪ Swagger UI (https://petstore.swagger.io) ▪ Swagger-diff (https://github.com/civisanalytics/swagger-diff)
- 6. SWAGGER DEFINES ▪ https://swagger.io/docs/specification/basic-structure/ ▪ Paths ▪ Operations ▪ Models ▪ Security Authentication
- 7. GENERATING CONTRACT FROM CODE ▪ SpringFox (http://springfox.github.io/springfox/) ▪ Can generate without running server by creating SpringTest that makes a MockMvc call to the swagger path ▪ Swagger Jax-rs (https://github.com/swagger-api/swagger- core/wiki/swagger-core-jax-rs-project-setup-1.5.x)
- 8. CONTRACT MUTATION TESTING ▪ Set your base api version ▪ On build: ▪ Generate spec from current code ▪ Pull base spec version from repo ▪ Compare spec versions ▪ On no difference, do nothing ▪ Non-breaking changes, update version ▪ Breaking change, fail build ▪ You can accommodate breaking changes by setting base api version ▪ Diff tool provides exactly what was changed in new version
- 9. SPEC AS MODEL ▪ Most of the parts of a CRUD server and all of the parts of a client are boilerplate ▪ The only difference is the domain model and operations, which are fully described by the contract ▪ Dozens of templates already created for both server stubs and clients ▪ Easy to generate your own template
- 10. IMPLEMENTATION OF CONTRACT BECOMES IRRELEVANT ▪ Servers or clients can be Java, Python, node, whatever you want ▪ Swap out an implementation with confidence ▪ Choose your communication protocol ▪ HTTP REST ▪ WSDL ▪ Protocal buffers ▪ Sync/Aync
- 11. SPLIT YOUR MONOLITH ▪ Grab the contract for a bounded part of your domain ▪ New microservice for it ▪ Replace old calls with calls to client
- 12. VERSIONED CLIENTS ▪ API structure no longer that important as long as the functionality is maintained ▪ Including api version with client calls allows for out of date detection ▪ Can send error message with updating instructions ▪ Can enable registered translations to service outdated clients by coercing into later versions
- 13. TEST CLIENTS ▪ Replace external http calls to in-memory datastores ▪ Can pull from examples embedded in contract to provide built in expected functionality
- 14. MY SERVER SETUP ▪ Generates Spring Boot app ▪ Controllers that correspond to api spec ▪ Base Interface, Dynamic Interface, Base Implementation, Dynamic Implementation ▪ Services for CRUD + stubs for additional operations (same components as Controllers) ▪ Spring Data Repositories ▪ Models with validation
- 15. EXTENDING THE CONTRACT ▪ Swagger allows for vendor extensions ▪ Add a key value pair with the key starting with x- prefix ▪ Example: ▪ EntityOperation (x-entity-operation) ▪ entity ▪ display ▪ operation ▪ subtype ▪ subtype-display
- 16. AUTOGENERATED UI ▪ Takes the swagger contract and generates section for each model ▪ Section has table, details panel, and linked subtypes
- 17. BEYOND IMPERATIVE API CONTRACTS ▪ What do we actually want to model? ▪ Declare that, let your generators handle the boilerplate mechanics and stub what cannot be captured
- 18. MY DREAM ▪ Effective model of domain entity graphs ▪ Fully captured semantic relationships ▪ Hierarchies supported automatically with nested set model ▪ Linked versus owned versus shared versus whatever else ▪ Semantic domain modeling ▪ Unique keys allow transparent specification of entity ▪ Properties identified as dimensions, comparable, dependent, etc. ▪ Contexts for models that need it, like for workflows ▪ Operations attached to entities and contexts ▪ All of the mechanics of this is hidden from consumers. They just works with entities