API-first development and the case for API mocking

One morning, you realize you have a great idea for an API. You discuss it with your team, then start building out the business case and technical requirements.  

Where do you go from there?  

You could write out the business requirements for the API and then code it. Or you could describe your API in a specification language, like OpenAPI, and use that definition to improve your team’s understanding of the API and do some early testing. 

But are either of these the best solution? 

  

API as a Contract 

The enterprise software industry is moving away from primarily monolithic systems. They’re headed to more distributed microservice architectures deployed on a private or public cloud. This change is also driving a move to API-first development, where teams define upfront business contracts between each other using APIs. 

Think of this API as a contract. By agreeing on the reason, you need an API (business case), describing what it needs to do (requirements). Then define the contract (design) before the development of the features coupled to this API begins. In this way, you enable your teams to work in parallel, and the producers and consumers of the API all get to collaborate.  

This is increasingly important if you adopt an API-first approach, where your organization treats APIs as a product in their own right. APIs are then considered the most important enabler of integrations and collaborations across the business, and a primary means of doing business with you. They’re also considered critical business assets. The importance of getting the API contract right early in the design and development process just went up a couple of notches. 

How mocks and contract testing accelerate API design first 

Contracts are fine as written definitions or documents, but an API is a business asset. You and your teams (and partners) are going to want to ‘try it out first.  Mocks and contract testing are important in validating the premise of the contract, and ensuring the requirements are all implemented effectively.  

Both API-first and API design-first emphasize the importance of design documents and contracts. They provide a reliable source of truth for API design and development teams. Both approaches get stakeholders involved early in the design process before any code is written. This process offers several advantages.  

Teams can work in parallel, using the API definition to create and mock APIs. This allows producers and consumers to try out API designs and test APIs before deploying them. There’s no need to wait on other teams to complete different phases of the API. 

Use API definitions and mocks. When these are hosted in tools like SwaggerHub, they automatically generate elements that improve the developer experience, such as interactive documentation, mocks to try it out, client libraries, and SDKs. 

Reduce your development costs by designing and testing early. Then reuse those components across multiple API projects. This is especially useful when implementing data domain models or standardizing status codes and error messaging.   

When testing integrations, contract testing ensures that a pair of applications will work correctly together. It checks each application in isolation to ensure the messages it sends or receives conform to a shared understanding that is documented in a contract.  

When used in the context of a single application, contract testing ensures an application’s behavior conforms to its documented contract (for example, an Open API specification) without reference to any particular consumer. 

Why understanding mock drift is essential 

In the Agile world of software development, with its fast pace and rate of change, it can be challenging to keep your mocks up to date, especially in a complex microservice architecture.  

When API definitions and mocks aren’t integrated, and mocks and live services deviate from one another due to rapid development updates, this is known as mock drift.  

This is a great use case where contract testing can help you keep pace with the changes in your service and reduce your need to keep mocks updated at a microservice layer. You can then focus your efforts to update mocks as part of less frequent integration tests. This way, you leverage contract testing and mocks as part of your development flows. Teams are able to accelerate with the right kind of test at the right time.  

SwaggerHub allows you to ‘auto-mock’ your API, based on the API definition, and use this for testing and demonstration purposes. The API Auto Mocking integration creates and maintains a semi-static mock of your API based on the responses and examples defined in your OpenAPI 3.0 or 2.0 definition.  

The mock is updated every time you save your API. The mock helps you test your API when designing it before it’s implemented by developers. The mock also allows developers to start building client applications before the API backend is ready. 

The design phase of an API benefits from mocking.  You can quickly and easily collaborate with stakeholders and apply changes to refine the API contract without waiting for a server deployment or the development team’s availability. With mocking, you can try out the changes and ensure they work as expected.  

API mocking speeds up collaboration and development, and reduces the dependencies between development teams, especially frontend and backend. It’s perfect when the API is still under development, and you want to avoid bottlenecks. 

Sometimes it’s necessary to make APIs available to others before they commit to using them. Mocking provides a simulation of the actual API for testing purposes without the need to give access to your product or provision credentials. Demos can benefit from API mocking in the same way.   

  

API-mocking case study 

A development company has been developing microservices. They used OAS-based APIs to communicate between microservices. Teams used to have to wait for one another to finish the APIs before starting work themselves. This dependency led to delays and frustrations which slowed projects down and caused stress.  

Using API mocks, they simulate their API schemas and defined behaviors. The teams use API mocks to develop both sides of their service in parallel, without having to wait on code to be written prior to testing.

For more information on API mocking and how to prevent mock drift, check out our on-demand webinar, API Mocking 102: How to Create Mocks and Prevent Drift