Context
Contract Driven Development leverages API Specifications as Executable Contracts to keep both consumers and providers working well with each other. If consumers and providers are referring to different versions of the API Specifications then it is not possible to guarantee this. This sort of deviation can happen when API Specifications are shared over documentation sites, email, or other non standard mechanisms.
It is critial to have a Single Source of Truth to store the API Specifications for all stakeholders.
Here is a video on this.
Treat Contract as Code
API Specifications are code and they are best stored in a version control system such as Git. This way we can leverage the version control system as a way to collaborate between all stakeholders through mechanisms such as Pull Requests, Merge Requests, etc.
Central Contract Repo - Single source of truth
File organization
Sample Central Contract Repository
- Package Naming Convention - In the sample repo we have the OpenAPI API Specifications organized in a manner similar to package naming convention. This helps in easy identifition of the approapriate files for organizations with large number of microservices and API Specifications.
- Specification file name - It is helpful to have the version number appended to the API Specification file name
- Extracting common schema - We recommend extracting common schema components to avoid duplications. Example: common.yaml contains only schema components which are leveraged as remote references in api_order_v1.yaml. This has other advantages too
- Consistency and standardisation - Commonly used parameter such as traceIds can be defined in one place and used across schemas
- Avoid duplication related issues - It is common to miss updating / renaming some parts of a schema, by extracting common code we can significantly reduce it
Pull Request / Merge Request Process
It is a good idea to prevent any direct commits to your master / main branch of Central Contract Repo. All changes have to go through a Pull Request or a Merge Request.
Pre-merge checks
- Syntax checks and Linting - We leverage Spectral for this. Read more about this here
- Specmatic Backward Compatibility Testing This step is crucial in identifying backward breaking changes to the specifications.
- Specmatic Backward Compatiblity Testing can compare two versions of the same file in Git to identify the difference. Please see this script where we are comparing the HEAD (top of the PR branch) and main (top of the master / main branch) for the changed files
- Specmatic returns a 0 or 1 just like any command line tool for success and error respectively based on which we can fail the build. At this point the team can decide if they should version bump the specification or change the code such that it is backward compatible
Sample Central Contract Repository with Pre-merge checks
Here are some sample pre-merge pipelines to disallow merges when specification changes have linter errors or backward breaking changes.
- Github Action
- Gitlab CI - This also uses Specmatic Docker Image
Collaborating over API Design
The goal of Central Contract Repo is to help all stakeholders collaborate over API Specifications thereby fostering better API Design. The Pull Request / Merge Request provides an avenue for anyone to propose an API change and others to review and comment on it. By automating the backward compatibility checks with Specmatic, the team is now able to focus on their domain and problem statement instead of worrying about accidentaly introducing backward breaking change in the API Design.
Referring to Contracts in Central Contract Repo
Specmatic.json
Both consumers and providers can leverage the specifications in the Central Contract Repository by listing it in Specmatic config. Example:
- Sample Consumer referring to api_order_v1.yaml as Smart Mock
- Sample Provider / API referring api_order_v1.yaml as Contract as Test
Specmatic will always pull the latest specification files from the version control system for both applications.