Join us on July 18th for a webinar on CI/CD Pipeline Optimization with APIs & K8s. Register now
Back to blog

Streamline Development with Effective API Mocking

Kay James
May 23, 2024 | 19 min read
API Mocking

Let’s say you’re building a new feature. You’ve gone through the API design and are trying to get the MVP running. Your frontend team is working on the front end, and your backend devs are building infrastructure and new APIs.

But frontend is going faster than backend. This is understandable, as your backend team has a ton of new APIs to spin up. But the front-end developers want to see what data will look like in their components, and work out how to render out different states based on the API responses. How can the frontend do this without the APIs being up and running?

API mocking lets you simulate the API responses, allowing frontend developers to continue building and testing their applications as if interacting with the backend services. We want to take you through this paradigm in detail, showing how it works, the advantages for all development teams, and how you can build API mocking tests into your CI/CD pipeline.

What is API Mocking?

API mocking is a technique used in API development to simulate the behavior of an API without interacting with the actual API. It involves creating a mock (or simulated) API version that mimics its functionality and responses.

The main purpose of API mocking is to allow developers to test and develop their applications independently of the actual API. It helps in scenarios where the real API is:

  • Not available: API mocking allows development to proceed when the actual API has not yet been implemented or deployed, by creating and managing mock APIs.
  • Is unstable: Mocking provides a stable environment for testing when the actual API is prone to downtime or errors.
  • Has limited access: When API usage is restricted by rate limits or costs, or is an external API with limited access, mocking enables unlimited testing without constraints.

By decoupling API integration development from the underlying API, mocking enables faster development and testing cycles, enabling developers to work more efficiently.

How API Mocking Works

API mocking works using mocking frameworks and libraries.

To create a mock API, developers use API mocking products like Blackbird, frameworks, and libraries to define the expected behavior and responses of the API. Mock objects mimic the behavior of the actual API objects or API endpoints. Developers configure mock objects to return predefined responses or exhibit specific behaviors when invoked by certain methods or endpoints.

Developers define the expected behavior of the mock objects by specifying the input parameters and the corresponding output or actions. This includes setting up expectations for method calls, return values, exceptions, and side effects.

Here’s the 10,000 ft view of how API mocking works:

1. Interception

In API mocking, interception refers to the process where the mocking framework captures outgoing API calls made by the application under test. This step is crucial because it allows the framework to intervene before the request reaches the API.

Tools like WireMock and Nock intercept HTTP requests and redirect them to mock endpoints. This redirection is typically achieved through application configuration changes or by integrating the mocking library directly into the application codebase, allowing developers to specify which calls should be intercepted.

2. Request Matching

Once a request is intercepted, the next step is request matching. In this phase, the mocking framework evaluates the intercepted request against predefined rules or patterns to determine which mock response should be applied. This involves matching various aspects of the request, such as the URL, HTTP method, headers, and body content.

Tools like MockServer provide extensive capabilities for detailed request matching, allowing developers to specify complex criteria that a request must meet to trigger a specific mock response.

3. Response Generation

After a request is matched, the mocking framework generates a response based on the predefined configuration. This response can vary from simple static data to highly dynamic responses generated based on the request's content.

Frameworks like Mirage JS are handy here, as they can generate sophisticated responses that simulate real-world API behavior, including database operations and conditional logic. This step ensures the mock API can support various test scenarios without needing real backend services.

4. Response Delivery

The final step in the API mocking process is response delivery, where the generated mock response is returned to the application. This response must mimic the actual API's behavior as closely as possible, including HTTP status codes, headers, and body content, to ensure that the application's response handling is accurately tested.

Tools like json-server deliver realistic responses quickly and efficiently, making it easier for developers to iterate rapidly on frontend functionality without being blocked by backend readiness.

Let’s now work through an example using one of the libraries above, Mirage JS. We’ll set up Mirage JS to mock a simple REST API for a blogging application that handles fetching a list of blog posts.

First, we have to set up a new project and install Mirage JS:

mkdir miragejs-example
cd miragejs-example
npm init -y
npm install miragejs

In that directory, we’ll then create a file named

This file will set up the Mirage server with routes to handle API requests. Here’s how you can define the server and a route to mock fetching blog posts:

import { createServer, Model } from 'miragejs';
models: {
post: Model,
seeds(server) {
server.create("post", { id: "1", title: "Introduction to API Mocking", content: "Learn about the benefits of API mocking." });
server.create("post", { id: "2", title: "Mirage JS: A Deep Dive", content: "Explore how Mirage JS can simplify frontend development." });
routes() {
this.namespace = 'api'; // This is where you tell Mirage to intercept requests for this namespace
this.get('/posts', (schema) => {
return schema.posts.all();


function and
class imports are used to set up a new mock server and represent data models that the server will manage, respectively. We can then use
to create a new Mirage JS server. The object passed as an argument configures the server, including its data models, initial data, and API routes.

We then define the data model that the Mirage server will use. In this case, a

model allows Mirage to create, store, and manage data for posts as if interacting with a real database. We then use the
function to populate the mock server with two posts when it starts. This seeded data, which simulates real data, can then be used immediately for development and testing.

In the

configuration, the
property sets the base URL path that Mirage will intercept. Here, it's set to
, meaning Mirage will handle all API requests that start with

A route handler for

requests to
is defined within the routes block. When a
request is made to
, the function provided to
is executed. The function retrieves all records for the
model, effectively simulating a response from a real API that queries a database to return all posts.

To test this, we’ll create a file named

to call the API. Since Mirage JS intercepts the requests, the data returned will be from Mirage’s server:

import './server'; // This imports the server setup
async function fetchPosts() {
const response = await fetch('/api/posts');
const posts = await response.json();

We’ll use

to serve the JS in a browser:

npm install -g parcel

Finally, we’ll create an


<!DOCTYPE html>
<html lang="en">
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Mirage JS Example</title>
<script src="index.js"></script>

Then, run the project:

parcel index.html

Open your browser to the URL provided by parcel (usually

). Open the console, and you should see the mocked data printed there, indicating that Mirage JS is intercepting your API calls and providing mock data in response.

Mirage JS Example

7 Advantages of API Mocking

  1. Faster Development: API mocking allows developers to work independently of the actual API, enabling parallel development and testing. Developers can start implementing and testing their code without waiting for the API to be fully developed or available. This accelerates the development process and reduces dependencies on external teams or services.
  2. Improved Testing: Mocking enables comprehensive testing of the application's interaction with the API. Developers can simulate various test scenarios, including success cases, error conditions, edge cases, and performance issues. Tests can be run quickly and repeatedly without relying on the availability or stability of the actual API. Mocking allows for better test coverage and helps identify bugs and issues early in the development cycle.
  3. Isolation and Dependency Management: API mocking isolates the application code from external dependencies, such as databases, network services, or third-party APIs. It allows developers to focus on testing the application logic independently without requiring real API connections or data setup. Mocking helps manage dependencies and reduces the risk of tests failing due to external factors beyond the developer's control.
  4. Faster Test Execution: Mocked APIs respond quickly, eliminating the latency and overhead of real API calls. Tests that involve mocked APIs run faster than tests that interact with the actual APIs. Faster test execution enables developers to run tests more frequently and get quicker feedback on the application's behavior.
  5. Controllability and Predictability: API mocking gives developers complete control over the API responses and behavior. Developers can define specific responses, simulate error conditions, or introduce delays to test various scenarios. Mocking ensures predictable and consistent behavior during testing, eliminating the variability and inconsistencies that may occur with real APIs.
  6. Cost Reduction: Mocking can help reduce costs associated with using real APIs, especially in the development and testing phases. Some APIs may have usage limits, throttling, or pricing tiers based on the number of requests. By mocking the APIs, developers can avoid consuming real API resources and incurring unnecessary costs during development and testing.
  7. API Contract Testing: API mocking can be used for contract testing, which verifies that the application and the API adhere to a predefined contract or specification. Developers can create mock APIs based on the agreed-upon contract and test the application against those mocks. Contract testing helps ensure compatibility, catch breaking changes, and maintain the integration integrity between the application and the API.

API mocking gives development teams faster development cycles, improved testing capabilities, better isolation and dependency management, and cost savings. You can use API mocking to enhance the overall efficiency and quality of the software development process.

Integrating Mock APIs with CI/CD Pipelines

Writing API mocks alone, as we did above, is an excellent way to quickly test and build different components of your application. However, API mocks are most efficiently used in continuous integration and continuous deployment (CI/CD) pipelines.

By integrating mock APIs into CI/CD pipelines, development teams can achieve several benefits:

  • Faster feedback loops: Tests can be run quickly and frequently, providing rapid feedback on the application's behavior and catching issues early.
  • Improved reliability: Mock APIs help ensure that the application functions as expected, even when the real APIs are unavailable or unstable.
  • Efficient deployment: Mock APIs facilitate smooth deployments by validating the application's compatibility and behavior in target environments.

Let’s say we’re using unittest.mock to mock some API functionality. The basic API fetch looks like this:

import requests
def fetch_data(url):
response = requests.get(url)
if response.status_code == 200:
return response.json()
return None

We can then write a test using unittest to mock the response from the API:

import unittest
from unittest.mock import patch
from app import fetch_data
class TestFetchData(unittest.TestCase):
def test_fetch_data_success(self, mock_get):
"""Tests successful API call."""
mock_get.return_value.status_code = 200
mock_get.return_value.json.return_value = {'key': 'value'}
result = fetch_data('')
self.assertEqual(result, {'key': 'value'})
def test_fetch_data_failure(self, mock_get):
"""Tests failed API call."""
mock_get.return_value.status_code = 404
result = fetch_data('')
if __name__ == '__main__':

Here, we’re using the

unittest.mock patch
function to replace the actual
call with a mock that we can control, allowing us to simulate different response scenarios for our API without making real network requests. This enables testing how our application code handles various API responses, such as successful data retrieval or handling errors, in a predictable and repeatable manner.

We can then use GitHub Actions to run tests against this API fetch using patch whenever we commit new code. This way, we can ensure that any changes made to the codebase maintain the expected functionality and do not introduce regressions or bugs.

All we need is to add a

file in a .github/workflow directory in our repository:

name: Python application test
branches: [main]
branches: [main]
runs-on: ubuntu-latest
- uses: actions/checkout@v2
- name: Set up Python 3.8
uses: actions/setup-python@v1
python-version: 3.8
- name: Install dependencies
run: |
python -m pip install --upgrade pip
pip install requests
- name: Run tests
run: |
python -m unittest discover -s .

This will run any unit tests automatically whenever new code is pushed to the `main` branch, or a pull request is made against it.

Phyton application test

By including these mock API tests in the GitHub Actions workflow, developers can automatically verify each change against the expected behaviors scripted in the tests, thus improving code quality and reducing the likelihood of unexpected issues in production environments.

Advanced Mocking Techniques

The above examples show mocking a basic response from an API. However, APIs have advanced functionalities, and you need to test your code against all their components before integrating with them.

Advanced mocking techniques are essential for handling complex scenarios and interactions in API testing. Here are some advanced mocking methods that you can consider integrating into your testing strategy:

Dynamic Responses

Dynamic data generation allows the mock to generate and return data that changes dynamically with each request rather than returning static predefined responses. This is useful for testing how your application handles varied data under different scenarios. Techniques include:

  1. Randomized Data: Use libraries like Faker in Python to generate random but realistic data sets, such as names, addresses, and emails. This randomness helps ensure that your application can handle various input data.
  2. Template Systems: Employ templates with placeholders for dynamically populated fields at runtime. This can include variable error messages, user data, timestamps, and more.
  3. Data Pools: Rotate through a set pool of data scenarios, which can mimic the behavior of a database with a finite set of rows. This is useful for testing caching mechanisms or load balancing.

For example, in Python, you can use

to dynamically generate test data:

from faker import Faker
import unittest
from unittest.mock import patch
from myapp import process_user
fake = Faker()
class TestProcessUser(unittest.TestCase):
def test_user_processing(self, mock_fetch):
# Generate a fake user profile
user_profile = {
"address": fake.address()
mock_fetch.return_value = user_profile
# Test the function that processes the user data
result = process_user(1) # Assumes process_user calls fetch_user_data internally
self.assertIn(user_profile['name'], result)

Conditional Responses

Conditional responses allow your mock APIs to react differently based on the specifics of the request, which can help in testing the application's decision-making pathways:

  1. Path-Based Conditions: Implement logic within the mock to provide different responses based on the URL path or query parameters. This is useful for APIs that serve different resources or actions based on the URL.
  2. Header-Based Responses: Vary responses based on headers, such as content type or authentication tokens, to test how the application handles various types of requests or levels of access.
  3. Behavioral Adaptation: Configure the mock to adapt its behavior based on previous interactions with the client. This simulates scenarios where subsequent responses depend on the history of the API usage.

Stateful Mocks

Stateful mocks simulate APIs that maintain state across multiple interactions, which is essential for testing sequences of requests where the outcome depends on the state:

  1. Session Simulation: Maintain user sessions through mock APIs to test features like login sequences, shopping carts, or any multi-step process that requires user context.
  2. Sequential Operation Testing: Use stateful mocks to verify operations that must occur in a specific order, such as creating, updating, and deleting a resource.
  3. State Transition Validation: Ensure that the application correctly handles state transitions, such as from an "in-progress" state to a "completed" status, reflecting real-world operations.

Error and Exception Handling

Error and exception handling in mocks is crucial for ensuring your application can gracefully handle API failures:

  1. Simulating HTTP Errors: Mock responses to simulate various HTTP status codes (like 400, 404, 500) to test how your application responds to different error conditions.
  2. Exception Throwing: Configure mocks to throw exceptions under certain conditions to ensure your application can catch and handle these exceptions appropriately.
  3. Timeout Simulation: Emulate network timeouts or long response delays to verify that the application can handle timeouts effectively by retrying requests or failing gracefully.

For instance, you should always have testing for rate limit errors for API mocking. With unittest we can add a rate limit exception and a test against it:

import unittest
from unittest.mock import patch
from app import fetch_data
class TestFetchData(unittest.TestCase):
def test_rate_limit_handling(self, mock_get):
"""Tests handling of rate limiting API responses."""
# Configure the mock to simulate a 429 error
mock_get.return_value.status_code = 429
mock_get.return_value.json.return_value = {'error': 'rate_limit_exceeded'}
# Call the function that makes the API request
result = fetch_data('')
# Check if the function handles rate limits correctly
self.assertEqual(result, "Rate limit exceeded, please try again later.")
if __name__ == '__main__':

API Mocking as a Development Accelerator

API mocking is an invaluable technique in software development, allowing teams to simulate API behaviors and responses without relying on actual backend services. By integrating API mocking into your development and testing workflows, you can accelerate development cycles, enhance testing efficiency, and improve the overall reliability of your applications.

Whether you're working to align frontend and backend development timelines or aiming to ensure your application can gracefully handle real-world scenarios, API mocking provides the control and flexibility needed to develop high-quality software. As technology evolves, so too does the importance of mastering such techniques, which are crucial for modern CI/CD pipelines and ensuring seamless, continuous delivery of services.