What is API Mocking? A Developer's Guide

API mocking is one of those techniques that sounds simple until you realize how many problems it solves. This guide explains what API mocking is, why developers reach for it, when it helps and when it does not, and how to start using it today.

What is API mocking?

An API mock is a simulated version of a real API. Instead of sending requests to a live backend, your code sends them to a local mock server that returns pre-configured responses.

The mock behaves like the real API from your code's perspective—same URL structure, same headers, same response shape—but it does not actually execute the real logic. It returns whatever you tell it to return.

This is different from:

• API stubs: Usually simpler, fixed-return values with no URL-matching logic.
• API fakes: Full in-memory implementations of the API logic—more realistic but heavier to maintain.
• API sandboxes: Test environments provided by the API vendor (like Stripe's test mode).

Mocks sit in the middle: they are real enough to test real behavior, but lightweight enough to run locally and configure in seconds.

Why developers use API mocking

Unblock parallel development

The most common reason. Your frontend team is building a checkout UI. The backend API that powers it does not exist yet—it is in a different sprint. Without mocking, the frontend team is blocked.

With a mock, you define the expected API response, run the mock server, and the frontend team works against it as if the backend were already done. When the real backend ships, you swap the mock for the live endpoint. If the response shape matches, nothing breaks.

Test edge cases and failure scenarios

Live APIs do not fail on demand. You cannot ask Stripe to return a 429 rate limit error right now so you can test your retry logic. You cannot make your payment API return a 500 to test your error state UI.

A mock server can. You configure the mock to return any response you want—timeout, 503, malformed JSON, unusual headers—and run your tests against it. Your error handling gets tested before production shows you it was broken.

Remove external dependencies from tests

Tests that hit live APIs are fragile. They fail if the API is down. They fail if your internet connection drops. They are slow because network I/O is slow. They sometimes change behavior when the API updates.

Tests against a mock server are fast, deterministic, and run offline. You get consistent results in CI regardless of the state of external services.

Reduce API costs and rate limits during development

Some APIs charge per request or have strict rate limits. Running your full test suite against the OpenAI API or a payment processor API on every CI run burns credits and risks hitting limits.

Mocking those APIs in development and CI means you only pay for real API calls when you actually need them—integration tests, staging validation, production traffic.

When not to mock

API mocking is not always the right answer. It is worth being honest about when it is not.

When the real behavior is complex and hard to replicate: If the mock does not accurately reflect what the real API does, you are testing against a fiction. This is especially true for stateful APIs where the sequence of operations matters.

When you need to validate the real integration: Mocks prove your code handles the expected response shapes. They do not prove the real API actually behaves as you expect. You still need end-to-end tests against real endpoints before you ship.

When the API has good sandbox support: If Stripe test mode, GitHub's API, or another vendor already gives you a safe, controllable test environment, use it instead of building your own mock. Their sandbox is more faithful to the real behavior.

The useful mental model: mock for development speed and unit test isolation, use real or sandbox APIs for integration and end-to-end testing.

How to mock an API with APXY

APXY includes a mock rules engine that intercepts specific requests and returns configured responses. You can set it up in about two minutes.

Step 1: Start the proxy

apxy start --port 8080

Step 2: Add a mock rule

You can add rules through the Web UI or the CLI. From the CLI:

apxy rules add \
  --match "POST api.stripe.com/v1/payment_intents" \
  --status 200 \
  --body '{"id":"pi_mock","status":"requires_payment_method"}'

From the Web UI, open the Rules tab, click Add Rule, fill in the URL pattern, status code, and response body.

Step 3: Route your app through APXY

HTTPS_PROXY=http://localhost:8080 node your-app.js

Any request to api.stripe.com/v1/payment_intents now returns the mock response. Your app never reaches Stripe.

Use a pre-built mock template

APXY ships with ready-to-use mock templates for common APIs. Import the Stripe Mock Kit, OpenAI Mock Kit, or GitHub API Mock Kit with a single command and get a realistic set of mock rules without writing them yourself.

curl -fsSL https://raw.githubusercontent.com/apxydev/apxy/main/mock-templates/stripe/rules.json \
  -o stripe-rules.json
apxy rules import stripe-rules.json

Common use cases and examples

| Use case | What you mock | What you get | |---|---|---| | Frontend dev without backend | All backend API endpoints | Frontend team unblocked immediately | | Error state testing | 500, 429, 503 responses | Error UI validated before prod | | Offline development | Any external API | Works without internet access | | CI without API keys | Third-party APIs | Fast, deterministic, no credentials | | AI agent testing | LLM completion endpoints | Deterministic responses for agent logic |

Summary

API mocking is a development technique where you replace a live API with a local server that returns pre-configured responses. It unblocks parallel development, makes tests fast and deterministic, lets you test failure scenarios, and reduces external API costs during development.

The key trade-offs: mocks are great for isolation and speed, but they do not replace integration tests against real endpoints. Use both.

If you want to try it now, install APXY for free and import one of the mock templates to get started in under five minutes. The basic API mocking example walks through the full workflow from capture to mock to replay.