All aboard! Mocking, simulating and documenting APIs for easier onboarding

Part 2 of the Modern API Mocking Series

‍
“Soon we’ll be making another run…And love, exciting and new, Come aboard, we’re expecting you…”

– Theme from The Love Boat, American television program, circa 1977

‍

In our first post of this series, Eric Newcomer introduced API mocking as a methodology for improving developer productivity and quality. 

If software is eating the world, then APIs are eating software. Investment in the API economy is increasing. More than 200 million APIs are already out there in the world, and more than 24,000 are publicly available as of 2022, and surely these figures have only skyrocketed since then.

APIs were supposed to ease the journey of creating innovative new features and services within internal and external-facing applications, while making integration smooth sailing. 

Unfortunately, leveraging API services within your own application development process often feels less like stepping onto the welcoming deck of The Love Boat, and more like getting marooned on an island for the next season of Survivor.

Developers want to build functionality that delivers the maximum business value—with a minimum of effort—so don’t leave them stranded when they are trying to consume APIs. 

Barriers to API onboarding

The process of adding some API calls to an application seems quite simple in comparison to the old days of web services and integration buses. A provider publishes an API with a Open API spec, and developers connect to it. Unfortunately, onboarding seldom works out that simply for several reasons:

• Poor documentation. While there may be a Swagger or Postman file sitting there for reference, chances are the documentation isn’t updated as often as the API, nor does it provide helpful instructions or code samples that help developers structure their own calls.
  
  
• Inconsistently available sandboxes. All too often, there isn’t a reliable way to try out the API, thereby wasting developer’s time and impacting quality. Further, sandboxes are hosted in temporary instances or unscalable architecture that can lag or go down at any time. Complex test scenarios like load testing or negative testing may be disallowed or rate-limited, and teams may have scheduling conflicts over a limited number of sandbox environments.
  
  
• Poor maintenance. Test API environments are often poorly maintained, and further, API producers don’t usually update test instances or inform developers about changes and downtime until after the events have already passed.
  
  
• Downstream dependencies. Any published API may have known or unknown downstream connections to other data services and API that can change or interfere with business logic or availability.

Simulating success with API mocking

Developers need a great onboarding experience to successfully make that first successful call, and then they need support on a continuous basis as they productively incorporate APIs into their app.

DevOps methodologies recommend automation at every stage of the continuous delivery pipeline, with “shift left” early testing and validation of all components that will make up the finished application. That’s certainly helpful, but for API development in particular, a lack of ready sandboxes leaves developers doing the cumbersome work of prototyping test APIs for early consumption, when they would rather spend their time developing and testing features.

The practice of API mocking allows developers to simulate the stateful behavior of a responsive live API service, even if the producer of that service hasn’t yet provided a live version or test environment.

The WireMock Cloud solution provides an on-demand environment with sophisticated API mocking that can be generated from specifications, Swagger definitions or even from live service traffic. The resulting mock API instances are addressable just like live production APIs, but because they are hosted in a stable multi-tenant cloud environment, they often prove to be ‘better than the real thing’ in terms of availability, performance, and predictability.

In essence, a mock API automatically represents a solid reference documentation, with an accompanying OpenAPI spec of the producer’s target API. It also makes every API consumed by developers more modular, because teams can consume and share the mock API assets and specs when collaborating on contract tests and reproducing results.

Where to start? Just create mocks and embed them in your developer portal, so every API also has a matching prebuilt mock. With this packaging, API mocks can be used as a smart, reliable sandbox which will improve the onboarding developer experience for APIs in your developer portal.

Building an API playground at Zenus

Zenus is a US-based independent bank and fintech company that provides banking APIs for business and institutional customers to interface with their banking and cross-border payment services.

Since many of Zenus’ prospective end customers will want to develop their own digital services using the bank’s APIs, the team launched an “API Playground” developer portal to ease new customer onboarding and improve customer retention, by allowing them to test complex business scenarios in an unconstrained environment, before they go to production. 

Rather than spending months building and maintaining their own test environments and mock server backends, the Zenus development team now keeps their mock API playground up to date by simply updating their Swagger files, or allowing WireMock Cloud to read live production specs directly from the API gateway.

“The main benefit of WireMock is the speed in which our team can get a new feature or version in front of our customers,” said Gabriel Duchateau, Head Of Solutions, Zenus Bank. “Creating new environments takes hours instead of days or weeks.”

The Intellyx Take

Who wants to build more APIs, and maintain additional sandbox infrastructure, just to test APIs? 

The most valuable resource of any developer is time, so don’t give them a frustrating reason to jump ship before they’ve even onboarded. API mocking simulates production APIs and provides useful documentation, in a ready-to-consume environment developers will love. 

API mocking allows teams to work in parallel, eliminating constraints and returning time to every turn of every development cycle. It’s all smooth sailing from here!

*Note, this blog by guest analyst Jason English from Intellyx originally ran in DevOps.com, read that article here.

©2024 Intellyx B.V. Intellyx is editorially responsible for this document. No AI bots were used to write this content. Image source: Adobe Express AI. At the time of writing, WireMock is an Intellyx customer.

‍