---
title: "The Complete Guide to API Mocking - API7.ai"
description: "Configure static and schema-based API mocks with Apache APISIX. Learn when to use a stateful mock server and how to prevent mock drift in testing."
url: "https://api7.ai/blog/complete-guide-to-api-mocking"
---

[Blog](https://api7.ai/blog)

[Products](https://api7.ai/category/products)[Technology](https://api7.ai/category/technology)[Ecosystem](https://api7.ai/category/ecosystem)[Case Study](https://api7.ai/category/usercase)[Team & Community](https://api7.ai/category/community)

Search

⌘ + K

[Blog](https://api7.ai/blog)

Technology

# The Complete Guide to API Mocking

[![Yilia Lin](https://github.com/Yilialinn.png)](https://github.com/Yilialinn)

[Yilia Lin](https://github.com/Yilialinn)

June 16, 2025

[Technology](https://api7.ai/category/technology)

API mocking returns a simulated response without depending on a live backend. It lets a client team agree on a response shape and test error handling while the real service is still being built. A mock is useful for development and contract discussion; it does not prove that the eventual backend behaves the same way.

For a definition and terminology, see [What Is API Mocking?](https://api7.ai/learning-center/api-101/api-mocking). This guide focuses on choosing a mock behavior, configuring a gateway example, and deciding when to use a dedicated mock server.

## Choose the Mock Behavior First

| Need                                            | Appropriate starting point                                        | Limitation to test                                                  |
| ----------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------- |
| One known status, body, and headers             | A static response on a gateway route                              | The same request normally gets the same response.                   |
| A response with generated values                | Schema-generated response, where supported                        | Generated values do not model business rules or persisted state.    |
| Several related calls, such as create then read | A stateful mock server or test fixture                            | A stateless gateway response cannot remember a created order.       |
| Consumer-visible failures                       | Separate routes or scenarios returning expected 4xx/5xx responses | A mock cannot replace testing real dependency failures and retries. |

Before configuring any tool, write down the request method and path, example success response, error cases, authentication expectations, and the contract version. Keep the mock in a test environment and use synthetic data rather than production credentials or customer records.

## Configure a Static Mock in Apache APISIX

The Apache APISIX [mocking plugin](https://apisix.apache.org/docs/apisix/plugins/mocking/) can return a configured status, body, and headers without forwarding the request to its upstream. This example assumes a running APISIX instance with the Admin API at `127.0.0.1:9180`, the proxy at `127.0.0.1:9080`, and a valid admin key stored in `ADMIN_API_KEY`. Do not expose the Admin API or put its key in a client-facing example.

```
curl -i "http://127.0.0.1:9180/apisix/admin/routes/mock-order" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "uri": "/mock/orders/42",
    "methods": ["GET"],
    "plugins": {
      "mocking": {
        "response_status": 200,
        "response_example": "{\"id\":\"42\",\"status\":\"pending\"}",
        "response_headers": {"X-Mock-Scenario": "order-pending"}
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {"httpbin.org:80": 1}
    }
  }'

curl -i "http://127.0.0.1:9080/mock/orders/42"
```

The route includes an upstream to match the documented route configuration, but the enabled `mocking` plugin returns the response before forwarding this request. Expect HTTP 200, an `X-Mock-Scenario` header, and the configured JSON body. This is a **fixed response**, not a persistent order service. The example uses an HTTP test upstream; use an approved test target in your own environment.

Change `response_status` and `response_example` on a separate test route to exercise a specific failure, such as a 503 response. APISIX also documents a `delay` attribute in seconds. Use delays and failures deliberately, then assert that the client handles the exact status and timeout behavior you configured.

## Generated Responses Are Not Stateful Workflows

The same [APISIX plugin](https://apisix.apache.org/docs/apisix/plugins/mocking/) accepts a `response_schema` object instead of `response_example` to generate a mock body. For example, a schema can describe an object containing a string `id` and a boolean `ready` value:

```
{
  "response_schema": {
    "type": "object",
    "properties": {
      "id": {"type": "string"},
      "ready": {"type": "boolean"}
    }
  }
}
```

Place this object inside the route's `mocking` plugin configuration. If both `response_example` and `response_schema` are set, **`response_example` takes precedence**, so remove it when testing generated data. The schema can produce values with the declared types, but it does not enforce a business workflow or guarantee realistic relationships between fields.

If a test must create an order, retrieve the same order later, expire a token, or vary behavior by a sequence of requests, use a stateful mock server or a controlled test service. Do not describe those behaviors as native APISIX `mocking` capabilities. Keep the gateway in front only when you also need to exercise its routing or configured policies.

## Keep Mocks Aligned With the Contract

1. **Version the contract.** Store an OpenAPI definition or agreed examples with the client and backend code. A mock response is not a substitute for contract validation.
2. **Cover meaningful cases.** Include success, invalid input, unauthorized access, dependency failure, and any documented rate-limit response. Do not generate arbitrary error percentages without a test objective.
3. **Assert, do not merely display.** In CI, compare status, relevant headers, and response shape with expected values. Run a separate integration test against the real service when it becomes available.
4. **Prevent drift.** Review mock fixtures whenever the API contract changes. Remove or isolate mock routes before exposing production traffic.
5. **Keep the boundary clear.** A mocked route may be useful for client development, but it cannot establish real backend latency, reliability, authorization, or data consistency.

## When to Use Which Tool

Use a gateway mock for a small number of fixed or schema-generated responses when the gateway itself is part of the test. Use a dedicated mock server for stateful scenarios, request matching across many cases, or a large fixture library. Use contract and integration tests to validate the actual service. These are complementary layers, not interchangeable measures of production readiness.

Start with one documented request and response, verify the client against it, and replace the mock with a real-service test as soon as the backend is available. If you are evaluating gateway-based API delivery beyond mocking, review the [API7 Enterprise product](https://api7.ai/enterprise) separately from Apache APISIX's open-source plugin capabilities.

Tags:

[API Mocking](https://api7.ai/tags/api-mocking)

Share article link

Share

Related Posts

[![How to Differential-Test LLM Routing Changes](https://static.api7.ai/uploads/2026/11/16/5FzNRmiG_llm-routing-differential-testing.webp)](https://api7.ai/blog/llm-routing-differential-testing)

## [How to Differential-Test LLM Routing Changes](https://api7.ai/blog/llm-routing-differential-testing)

[![Partial API Outages Need Retry Budgets, Not Retry Storms](https://static.api7.ai/uploads/2026/11/10/Upkbmn88_api-retry-budgets-partial-outages.webp)](https://api7.ai/blog/api-retry-budgets-partial-outages)

## [Partial API Outages Need Retry Budgets, Not Retry Storms](https://api7.ai/blog/api-retry-budgets-partial-outages)

Table of Contents

- [Choose the Mock Behavior First](#choose-the-mock-behavior-first)
- [Configure a Static Mock in Apache APISIX](#configure-a-static-mock-in-apache-apisix)
- [Generated Responses Are Not Stateful Workflows](#generated-responses-are-not-stateful-workflows)
- [Keep Mocks Aligned With the Contract](#keep-mocks-aligned-with-the-contract)
- [When to Use Which Tool](#when-to-use-which-tool)

## Related Posts

[![The 2025 API Mocking Toolbox: 10 Expert-Picked Solutions](https://static.api7.ai/uploads/2025/06/16/oz8QcEz1_api-mocking-toolbox.webp)](https://api7.ai/blog/2025-api-mocking-toolbox-10-solutions)

Technology

June 16, 2025

#### [The 2025 API Mocking Toolbox: 10 Expert-Picked Solutions](https://api7.ai/blog/2025-api-mocking-toolbox-10-solutions)

Discover 2025’s top API mocking tools like Postman, WireMock, and Zuplo. Streamline workflows, cut testing costs by 40%, and accelerate development with CI/CD integration.

[API Mocking](https://api7.ai/tags/api-mocking)

[![HTTP/3 Changes API Debugging: Observe at the Termination Point](https://static.api7.ai/uploads/2026/11/17/ofz6Efrg_http3-api-observability.webp)](https://api7.ai/blog/http3-api-observability)

Technology

November 17, 2026

#### [HTTP/3 Changes API Debugging: Observe at the Termination Point](https://api7.ai/blog/http3-api-observability)

Debug HTTP/3 APIs by separating QUIC transport, protocol termination, gateway policy, and service behavior, then correlate telemetry across every hop.

[API Observability](https://api7.ai/tags/api-observability)

[HTTP/3](https://api7.ai/tags/http/3)

[QUIC](https://api7.ai/tags/quic)

[![Short Links Are Redirect APIs: Design Them for Safe Retirement](https://static.api7.ai/uploads/2026/11/17/KKWi8TNC_short-link-redirect-security.webp)](https://api7.ai/blog/short-link-redirect-security)

Technology

November 17, 2026

#### [Short Links Are Redirect APIs: Design Them for Safe Retirement](https://api7.ai/blog/short-link-redirect-security)

Treat short links as production redirect APIs with owned domains, destination policy, status-code discipline, monitoring, and non-reusable retirement.

[API Security](https://api7.ai/tags/api-security)

[API Lifecycle](https://api7.ai/tags/api-lifecycle)

[URL Redirects](https://api7.ai/tags/url-redirects)
