How to simulate API latency during development using Hoverfly

Simulating API latency during local development allows you to write code that will deal with it gracefully. This blog will cover how you can simulate API latency using a simulation tool — Hoverfly.

What is API latency?

API latency is the total amount of time taken by an API system to respond to an API call. It is the delay experienced by a user after initiating a web service or an action taken in the mobile app while in an active session. In an on-demand society it is important to maintain an acceptable API latency, if your website or mobile apps are slow this will direct your customers to competitors.

What is Hoverfly?

Hoverfly logo

Hoverfly is an open source HTTP service virtualization tool that is commonly used to simulate API dependencies.

It can be used to:

• Replace slow, flaky API dependencies with realistic, reusable simulations
• Simulate network latency, random failures or rate limits to test edge-cases
• Export, share, edit and import API simulations

Getting started

In order to get started install Hoverfly here. It comes with a command line tool called hoverctl. Open a command prompt and change the directory to the Hoverfly folder, to run Hoverfly with the following command:

hoverctl start

This will return the admin and proxy port Hoverfly is running on.

Hoverfly running

By default, the admin port is 8888 and the proxy port is 8500, if you want to update the port numbers you can run the command below, replacing the port numbers:

hoverfly -ap {adminPortNumber} -pp {proxyPortNumber}

Capture mode

Hoverfly capture mode

In Capture mode, Hoverfly intercepts communication between the client application and the external service. It records outgoing requests from the client and the incoming responses from the service API. Usually, Capture mode is used as the starting point in the process of creating an API simulation. Change to capture mode with the following command:

hoverctl mode capture

Within a microservice architecture it is common for applications to depend on API’s from another team or even a third party. For example a car leasing application may rely on a third-party service such as Worldpay to process payments or a blogging website such as Medium may authenticate users via social networking websites such as Twitter or Facebook.

In this example we are going to simulate a delay to this public weather forecast API. From Swagger or Postman, call the API you want to simulate. To export your capture, type the following command:

hoverctl export simulation.json

Adding delays to simulations

API simulations are stored as JSON files, which conform to the Hoverfly schema. For the weather forecast example, the simulation looks like this. Simulations can be exported, edited and imported in and out of Hoverfly. You can apply “delays” or “delaysLogNormal” to responses. Delays can be applied selectively according to request URL pattern and/or HTTP method. By default the delays are set to empty in the simulation file.

“globalActions”: {
        “delays”: [],
        “delaysLogNormal”: []
}

To add a five second delay, edit the file so the “globalActions” property looks like this:

“globalActions”: {
“delays”: [
      {
        “urlPattern”: “.”,
        “httpMethod”: “”,
        “delay”: 5000
      }
],
“delaysLogNormal”: []

Simulation mode

Each time Hoverfly receives a request, rather than forwarding it on to the real API, it will respond instead. No network traffic will ever reach the real external API.

To import the edited simulation.json file, switch to simulate mode by typing command:

hoverctl import simulation.json

Make the requests again using Swagger or Postman. The response will be delayed by five seconds.

To stop Hoverfly type the following command:

hoverctl stop

By playing around with delay timings we can see how our application performs when there is a delay from a third-party we rely on and handle it accordingly, as an example you could return a Request Timeout (408) or Service Unavailable (503) status code to handle this scenario gracefully.

Summary

One of the main benefits of Hoverfly is having the ability to simulate network latency, random failures or rate limits to test edge-cases, when carrying out local development. It also promotes a “shift-left” testing approach. In my experience, I have found non-functional requirements such as network latency or rate limits may only have been considered as an integration test or not considered at all.

Further reading:

Hoverfly Docs

Hoverfly Tutorials

Hoverfly as a proxy server