Why API Mocking Increases Alignment with Consumers
How can you reduce the risk of implementing the wrong API?
APIs that don't deliver what consumers look for are bound to fail. Consumers—and other stakeholders—are the reason an API exists. How can you, the designer, align all expectations before you start implementing an API?
This article is brought to you with the help of our supporter: Speakeasy.
Speakeasy provides you with the tools to craft truly developer-friendly integration experiences for your APIs: idiomatic, strongly typed, lightweight & customizable SDKs in 8+ languages, Terraform providers & always-in-sync docs. Increase API user adoption with friction-free integrations.
In 2023 I spent some time building an API from scratch. When I was near the end of the API Design process, I was tempted to take my findings and rush to implementation immediately. Instead of doing that, I wanted to make sure that all stakeholders understood how the API would behave. I wanted to get through a last feedback loop before starting the implementation, so I created an API mock.
Mocking things up is a great way to show people what a final work would look like without actually implementing the real thing. Mocks are essential to validate assumptions. Artist Dana Schutz makes a great point on this matter. She lives in the world of art, and even there, mocking seems to be critical.
Before I start a painting, I'll mock up what I think would be the right dimension and see how that physical interface can work on that scale with that subject. I really care about that before I start making a painting.—"I think of color as a material" with Dana Schutz (video), Louisiana Channel, February 7, 2023
By mocking up the work before working on the painting the artist was able to test the idea in an almost effortless way. In the case of Dana Schutz with "The Public Process," mocking was handy because the painting is almost three meters tall by six meters wide (9.5 ft by 19 ft). Imagine working on a painting that size only to find out it's not what you were expecting.
While many other artists follow a similar practice it's with industrial design that the practice of using mockups really shines. In its early years of experimenting with the Mac, Apple used mockups extensively to test ideas. Hartmut Esslinger, the designer behind those early concepts, wanted to test the products without having to build them first.
Among other materials, Apple used foam and plastic to build those mockups. At that time foam offered several advantages. It's easy to manipulate making it ideal for creating rapid experiments. It's cheap in comparison with plastic or metal. Even though it's not the real thing, foam offers a realistic representation of the final work.
Following a strategy where mockups are used as a validation tool allows companies like Apple to deliver products that meet the needs of consumers. It's cheap and easy to iterate on a physical product before it enters a factory production line.
Back in the world of APIs, it's easy to see how a similar mockup strategy can have enormous benefits. In "Building an API Product" I cover in detail the advantages of using an API mock. While the benefits aren't as evident as with mockups of physical objects you can still appreciate how mocking an API can alleviate your development process.
The greatest benefit of an API mock is that it lets consumers perform integration tests even before you implement the API. Being able to test how the API would behave as early as possible is what enables the alignment with consumers. One of the stages of the API Design process encourages you to validate the definition before implementation.
You can validate an API definition by presenting it to stakeholders and getting their feedback. However, they'd be able to offer a more complete opinion by interacting with your API. A mock server is therefore the best simulated experience of your API you can offer without having to implement it.
The more your mockup looks like your real API the better feedback you'll get. That happens because consumers suddenly suspend their disbelief once they interact with your API mock server. Seeing something working is much better than reading a definition document. Scott Hurff explains this concept in "Designing Products People Love." The author shows how Apple uses a system of high-fidelity mockups to obtain meaningful feedback. According to Hurff, whenever people interact with something close to the real product "disbelief is suspended, and true opinions flow out."
Back to my experience building an API, I first used the API mock myself to see if I could consume the API using common tools and programming languages. Then, I engaged with potential consumers and asked them to integrate with the API. I observed what they did and obtained analytics from their usage of the mock server. I used those analytics together with learnings from interviews to understand what consumers were feeling. With that information, I reviewed my assumptions and improved the API design to eliminate unnecessary friction.
Altogether, mocking an API is an activity that promotes alignment with consumers during the design stage. The higher the fidelity of the API mock server the better the feedback will be. Mocking an API reduces the implementation risks and improves the full API lifecycle.