An API-first development approach needs prototype-first thinking

“API-first” is the mantra for the right way to develop an API. Many people interpret this as starting with the OpenAPI specification, but an OpenAPI specification is complex and can require a lot of editing and rework when an API design is still changing – which is very often the case. 

It’s much better to create a prototype first, especially when reviewing the API with a business analyst or with the API consumer. 

The prototyping approach is comparable to the practice of mocking up a GUI on storyboards or wireframes and showing it to the user before starting to code the app.

The point is, you want to get feedback on the design before doing a lot of work that might have to be redone later if it doesn’t meet requirements.

Typical requirements include supporting a great customer experience, which users expect from mobile and web applications. 

The right kind of API delivers the right data to the app at the right time, and sends the data from the app to the database, as users expect. It’s not just the GUI, it’s also the API.  

Therefore an essential part of the API-first approach is confirming that the API supports the expected user experience, before starting development work. 

Basically this means working with the user (or the user’s proxy) on an API prototype to finalize the API prototype before designing the OpenAPI spec and generating the API.

In other words, prototyping or “API mocking” is a better approach to the API first design process, rather than starting with writing the OpenAPI spec.

Modern tooling should prototype APIs via API mocking. Once the design is finalized, the tooling should generate the OpenAPI spec from the mock.  

Designing APIs for complex business problems

As Grady Booch wrote in the introduction to Eric Evan’s Domain Driven Design, the complexity of the application domain is a direct result of the complexity of the business problem. 

In other words, complexity is inherent to the API design process for many applications. Handling complexity is therefore inherently part of the API mocking first approach. 

Sometimes the API consumer has difficulty expressing complex requirements. The best way to handle such complexity is to create a prototype of the API and iterate through the changes until it meets requirements. 

Working with an API prototype saves a lot of rework compared to starting with a formal specification or implementation. 

Furthermore, complex applications typically involve multiple APIs working together. Prototyping them together saves an order of magnitude more work. 

API design using third party APIs

As mentioned in the previous blog post, the current growth curve of APIs is off the charts. APIs are now the standard way of accessing third party services such as payments, location based lookups, address validation, text notification, etc. 

Third party APIs add complexity because every API provider does things differently. Some providers offer good support, great documentation, and a testing sandbox. Others do not. 

API developers can level the playing field through API mocking to make sure all third party APIs work the way you expect them to, regardless of whether they are available for testing. 

And it’s not enough to test whether the functionality is working. A big part of the experience users expect is that the application (and the APIs it depends on), is always available and performant. 

Mocking Multiple APIs to flag design issues 

When API design issues are discovered late in the development process, it can be very difficult and expensive to fix them. It’s much better to identify and fix them as early as possible, especially when there’s a mix of internal and third party APIs. 

API mocking takes the guesswork out of this validation process because it provides a realistic testing environment. Developers can mock up APIs in development and integration testing environments and test out how they interact with other APIs before finalizing the code. 

Mock-based API prototyping optimizes the API design process by discovering and fixing basic design issues in a safe environment, in other words, allowing you to fine tune the user experience under realistic conditions. 

Real World Example 

Bilt Rewards is a loyalty program that fills the market gap of using credit cards for rent payments. 

Most landlords don’t like to accept credit cards for rental payments due to the processing overhead, and usually, if they do, will pass along the processing charge to the renter. 

Renters sign up to the Bilt Rewards payment system to receive loyalty points for rental payments and for other qualified credit card purchases.

Bilt Rewards manages their payment and rewards services through a website and a mobile app, powered by a set of backend microservices APIs integrated with a set of third party APIs. 

They use the mocking solution from WireMock Cloud to accurately simulate system behavior during design, development, and integration testing by validating each API and its related flows, even when some of the third party or internal APIs aren’t completed or available. 

Mocking supports Bilt’s complex integration tests using proxies and finite state machines to step through the API orchestration flow. This not only helps flesh out the designs for the API specifications and stabilize them, but also helps them confirm the APIs deliver a great user experience. 

The Intellyx Take

The number of APIs under design and development is increasing exponentially. So too does the challenge of finalizing API-first designs for complex applications. 

Prototyping an API with a mocking tool such as WireMock Cloud helps take the complexity out of the API design process by getting the users involved in the design process early on, before any specification or implementation work. 

Bilt Rewards is a perfect case in point. Setting up and successfully running a points reward system for paying rent by credit card involves challenging internal logic as well as invoking any number of external, third-party APIs to handle different parts of the processing load. 

Getting it all running correctly as early as possible in the development life cycle is essential to the success of any new venture such as Bilt Rewards. 

Prototyping these interactions and thoroughly testing them with an API mocking tool such as WireMock Cloud not only improves quality, but also validates the business drivers behind such API-first designs before the tool generates the OpenAPI spec. 

Copyright © Intellyx BV. Intellyx is solely responsible for the content of this article. As of the time of writing, WireMock Cloud is an Intellyx customer. No AI chatbots were used to write this content. Image by lumaxart, via Wikimedia Commons

‍