API Contract Testing For A Design-First World
Today, API-driven microservices applications are a source of speed to innovation and competitive advantage – according to SmartBear’s most recent State of Software Quality – API report:
- APIs are becoming central to core internal business function: 70% of companies surveyed have been developing APIs for more than three years.
- And of this cohort, almost three-quarters of organizations consume and develop APIs themselves with the two most popular drivers being (1) to reduce development time and cost, and (2) interoperation between internal systems, tools, and teams.
However, this modern way of architecting software doesn’t come without challenges.
Neglecting to adapt a new approach to service architecture design with a new approach to the underpinnings – API design and testing – can undermine the efforts.
At the crux of the issue is the drift of an API design definition from reality. This can occur from either side of an integration point; for example, the provider may not actually implement the API definition. Or the consumer may misinterpret the requirements of the provider, and so we see misinterpretation and integration issues, or the teams ignore the designed API definition, resulting in an outdated, irrelevant document.
Drift can cause negative impacts to the software development lifecycle, giving rise to be often only caught later – usually after a code change has been pushed to a development or staging environment … or sometimes later. The task of uncovering bugs in this later stage is high and therefore increases the overall development time.
In this blog, I will discuss the concept of design-first API contract testing as the new best-practice approach for microservices software development – pairing sound API standards and governance frameworks with a thorough API testing approach enables teams of all sizes and configurations to scale the delivery of quality software, with speed.
An Introduction To API Design-First Approach
Put simply, an API design-first approach is all about speaking the same language. The highly popularized approach advocates for upfront design of API specifications, before writing any code, and recording this in a way that both humans and computers can understand.
Some may argue that this approach is slower; however, if we consider more than just the API design aspect of the software development lifecycle (SDLC), we will see that getting API design aligned upfront can be highly beneficial for the speed of delivery overall.
Benefits Of A Design-First Approach
Think of a design-first approach as the bridge between design and development. Benefits include:
- Getting Product and QA involved to create APIs with a product focus, known as product-driven API
- Empowering developers to use the API design and automation tools to accelerate development efforts
- Cross-functional teams – allowing API consumers, producers and technical writers to work in parallel
- Visibility of design and shorter feedback loops
- Validation of implementation before deploying to production making DevOps role easier
- The ability to be adaptable to changes throughout the development process
- Reduces the risk of specifications drifting from implementation
Read more about the benefits of an API design-first approach.
When Is A Design-First Approach Appropriate?
High-performing organizations choose a design-first approach to API development when:
- Developer experience matters.
- The delivery of the API is mission critical.
- Communication and alignment are paramount.
And many are now also choosing this to support API design in situations where a code-first approach was previously the preferred means:
- When there’s a need to deliver with speed
- For the creation of internal APIs
Like a design-first approach, API contract testing supports developer experience, decouples teams, and fits in as the missing piece to the puzzle, enabling development teams to speed to deliver on mission-critical APIs, supporting both internal and external use-cases.
An Introduction To Contract Testing And Why It’s Needed
Contract testing answers the question “Will my API behave the way that we agree it should?” It calms the chaos caused by complex, scaling microservices architectures. Teams who’ve implemented contract testing experience benefits such as:
- The ability to test a single integration at a time
- No need to create and manage dedicated test environments
- Fast and reliable feedback on the developer’s machine
- A simple API testing process that scales linearly as the business and the microservices grow
- Allows teams to deploy their services independently
Contract testing provides a level of ownership for quality for everybody onthe software development team. Because we’re getting confidence earlier with more specific, targeted testing, we can focus our end-to-end tests on their strengths – full application-level functionality – rather than picking up whether two individual APIs can speak to one another. This speeds up release cycles and reduces the effort required to manage dependencies, environments, and data.
As you can see, contract testing is the antidote to clawing back some of those pains that we might feel in a microservices architecture.
Watch the webinar: API Contract Testing for a Design First World
Implementing Contract Testing In Your Team
We are slowly seeing the introduction to both contract testing tools or existing tools providing a means to complete contract testing. In the past decade, the Pact specification has become known as the de-facto standard and is the most broadly adopted and trusted specification for contract testing. Pact supports more than 10 languages and is expanding its multi-protocol capabilities. Many chose Pact and self-hosted Pact Broker (where the contract is stored).
The alternative, for teams who prefer a hosted version, is PactFlow. As the complete solution to deliver contract testing at scale, PactFlow is built around the Pact framework, with added benefits such as security, user management, and the exclusive bi-directional contract testing framework.
How To Orchestrate API Design-First Contract Testing
Now to piece it all together. Setting up a design-first contract testing approach requires both a PactFlow and a SwaggerHub account. With these, you can follow a few steps and you’re up and running.
1. Authoring the OpenAPI definition file
This is going to be the source of truth that we use to kick off this entire workflow – the best place to do so is inside SwaggerHub.
2. Bring visibility of the consumer to the design phase
Using data from PactFlow, the consumer can now be made visible in the design phase to help us inform how we can change the design in such a way that won’t impact clients and also prevent breaking changes right back at the design. If needed, we can iterate on design, involve other stakeholders, and essentially sign off and publish new versions. Once we have published this design, we’ve now opened the ability for development and testing and other processes, documentation and so on. to kick off from this process. That can all happen in parallel.
3. Confirm OpenAPI Specification (OAS) expectations during development
So in the case of development, we can use the OpenAPI file to generate code that we can use to rapidly build either the consumer side of an integration point or the provider side of the integration point. This is where we introduce contract testing to get additional coverage – the API designer and developer will see how our consumers use a provider and verify the provider to make sure that it’s not out of sync with the consumer and out of sync with the actual OpenAPI document that we’re using. And there you have it, a means to prevent drift in development journey.
4. Functional test of the provider contract
Later in the SDLC, in the testing stage, we can build our test approach around the OpenAPI definition. A means to do so is to bring a functional testing tool, such as ReadyAPI, or open source tools like Dredd, which will read in an OpenAPI file, and then issue requests against your provider to make sure that it stays compliant. All the assertions that are built in will make sure that it’s compatible with that OpenAPI definition.
5. Gating a release with Can I Deploy
Once we have progressed past development and testing, it comes time to release. Teams can leverage the capabilities inside of PactFlow, where we’ve got all the visibility of the consumer contracts – what the consumer needs of a given provider,and what the providers can do, aka visibility about the integration across the ecosystem. We then ask the question “is it safe to release these changes?” using PactFlow’s Can I Deploy feature. No surprises here – because the OpenAPI definition has made its way through this journey, we know that it’s come from a source of truth tied directly to the actual design and implementation. We know it’s always up to date and it’s correct. And so we can know that documentation will get published and that this is going to be trustworthy.
All this is made possible with PactFlow’s exclusive bi-directional contract testing feature.
Why Do You Need This Approach, Now?
If your team experiences the symptoms of chaotic microservices sprawl – long lead time to deploy, bugs in production, coupled teams – it’s worth exploring a design-first contract testing approach. Using SwaggerHub and PactFlow will increase the quality of your design-first API development workflow and help navigate the complexity of microservice rollouts. Here are the outcomes you can expect:
- SwaggerHub can be used to unify teams around a single source of truth – the OAS.
- A foundation of a repeatable process for API development.
- PactFlow brings increased visibility into how consumers use your API.
- Development teams can work independently and safely to accelerate release cycles.
- Rapidly increase the coverage of tests across the system by reusing existing tests on both sides of an integration point to prevent easily avoidable breaking changes.
- Reduced need for API versioning.
- Using PactFlow’s bi-directional contract testing feature, teams can retrofit onto existing systems where those tools and processes already exist.
- Improves ROI of contract testing initiative.
Give design-first API contract testing a try for free with the PactFlow and SwaggerHub integration. Learn more.