The Complete Guide to API Mocking
June 16, 2025
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?. 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 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 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
- 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.
- 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.
- 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.
- Prevent drift. Review mock fixtures whenever the API contract changes. Remove or isolate mock routes before exposing production traffic.
- 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 separately from Apache APISIX's open-source plugin capabilities.



