Mock-first API prototyping: Ship API-dependent features more efficiently

Tom Akehurst

CTO and Co-founder

October 3, 2023

Table of Contents

This is some text inside of a div block.

Internal APIs are ubiquitous in modern software development. But the handover between the team that’s building the API and the team that’s meant to consume it tends to break down - resulting in late feedback and considerable delays in shipping features and products.

In our latest update to WireMock Cloud we’ve shipped a new API prototyping feature that allows developers to collaborate and iterate better, from the initial design discussions through integration testing. We’ll refer to this approach as mock-first API prototyping.

We’ll start by introducing the problem and the current approaches to solving it; if you’re in a hurry, you can scroll down to the new feature part, or check out our recent DevTalk webinar on this topic.

Developing internal APIs: the problem with whiteboards and shared docs

Here’s a pattern that should be very familiar if you’ve ever shipped code in a microservices or service-oriented architecture (SOA) environment, or developed software in partnership with another organization:

Team A is producing an API that team B needs to consume as part of a downstream software component. For example, Team A might be developing an updated user authentication API that Team B needs to incorporate in a mobile application front-end.
Before getting started, both teams get together and sketch out a blueprint of the eventual API.
Team A then goes away to build the component. Team B is stuck in limbo waiting for the API to be ready.
Several weeks later, Team A ships the API, and Team B can start developing against it.
Vigorous integration testing reveals many overlooked aspects from the design stage - such as missing fields or improper formatting.
This process repeats several times until a suitable API emerges and a client application can be integrated and shipped.

There are a few problems here:

Cycle times. The consuming team cannot start their work until the producing team is done. This often causes an overall delay in delivering the feature.

Late feedback. It’s a well-known fact that changes or course corrections made late in the software development process are always costly. The price for revising implementation designs mid-development can be quite high, much more so than if this feedback had arrived earlier.

Lack of reusability. The initial design scheme doesn’t result in a long-term asset. The rough sketches on a whiteboard or shared documents created during the initial sessions become obsolete once the execution is complete, and the next API design essentially starts from scratch.

Due to these issues, many teams have now adopted a different approach.

API-first design: a step in the right direction, but issues remain

With the rise of collaborative API authoring tools came a more modern approach to designing APIs, which we can call the API-first approach. In this approach, the API producer and API consumer teams start by collectively designing an OpenAPI spec, which then serves as the basis for further development.

Working against a standardized spec has several advantages. You can generate documentation and validation flows, and the risks of missteps during downstream development are smaller. You can also generate mock APIs based on this specification, which reduces dependencies and allows for faster parallel development.

‍

This approach helps compress timelines, and the reliance on a broadly-adapted standard improves reusability. But it also leaves a lot to be desired:

API specifications are challenging to use as the basis for brainstorming or as a starting point for thinking about API design. Most people don't intuitively think in terms of complete API specifications. Developers often prefer to start with examples and iteratively evolve generalized behaviors out of these instances, allowing the model to emerge naturally.
Feedback still arrives late. While collaborative authoring allows for more careful scrutiny of the API design, feedback from implementation-level interaction still arrives fairly late.
Limited scope of testing. Mocks of the kind generated by authoring tools, that can't be further enriched after generation tend only to cover a basic subset of behaviors and thus limit the scope of testing they can be used for.

Is there a way we can offer the same type of collaboration around accepted standards, sidestep these issues, and further increase efficiency? There sure is!

Introducing: Mock-first API prototyping in WireMock Cloud

A new approach to API prototyping, which we’ve seen emerge among WireMock users - and which we’ve now incorporated as a feature in WireMock Cloud - offers a more efficient way to build durable APIs, shorten feedback loops, and increase developer productivity. We call this mock-first API design.

The main idea here is that instead of starting with a theoretical API, the consumer and producer teams start by producing a working mock.

In this approach, teams collaboratively build a mock API during their design discussions. Because mocks are easy to create and modify and don’t require a separate coding effort, they work as an effective sketch tool. And the result of these design sessions is not just a spec but a functioning mock API that fully encapsulates the agreed-upon design.

The API-consuming team can immediately start developing against this mock API and performing end-to-end tests to identify potential issues - which means feedback arrives much earlier and adjustments can be made to the spec before significant development effort is wasted. The API-producing team can use the mock definitions to validate that the final API is delivering the expected outcome.

This mock then serves as the basis for generating comprehensive OpenAPI specifications and documentation (which can be done via WireMock Cloud). This eliminates much of the legwork typically associated with manually authoring an API specification.

Benefits of mock-based prototyping

The workflow we built into WireMock Cloud is similar to some of what our users were doing on their own with WireMock - but we’ve invested significant effort to make an end-to-end process that’s easy, collaborative, and suitable for the way organizations want to build modern software.

There are several benefits to this approach:

More realistic API specs - since we’re starting with examples rather than an abstract idea of an API, we’re less likely to make omissions and mistakes
Automation - the OpenAPI spec can be partially auto-generated in WireMock Cloud
Faster development - the API consuming team can start building immediately against a functional mock
Feedback arrives early - making it cheaper and faster for the producing team to make revisions
CI/CD - WireMock provides a ready-made sandbox for CI/CD and developer enablement post-implementation
Easy onboarding for consuming teams via the WireMock Cloud UI (and integration with developer portals such as Backstage, which is coming soon!)

What this looks like in practice

In our recent DevTalk, we demoed the process from start to finish. Watch the full webinar here, or the tutorial part below:

Get started with API prototyping in WireMock Cloud

Want to try the new functionality for yourself? It’s as simple as logging in to your WireMock Cloud account (or creating a free account). You can reach the prototyping portal by creating a new mock API (https://app.wiremock.cloud/mock-apis/create) and choosing ‘OpenAPI’:

‍