---
title: mocking
keywords:
  - Apache APISIX
  - API Gateway
  - Plugin
  - Mocking
description: This document contains information about the Apache APISIX mocking Plugin.
---

<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements.  See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License.  You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
-->

## Description

The `mocking` Plugin is used for mocking an API. When executed, it returns random mock data in the format specified and the request is not forwarded to the Upstream.

## Attributes

| Name             | Type    | Required | Default          | Description                                                                            |
|------------------|---------|----------|------------------|----------------------------------------------------------------------------------------|
| delay            | integer | False    |                  | Response delay in seconds.                                                             |
| response_status  | integer | False    | 200              | HTTP status code of the response.                                                      |
| content_type     | string  | False    | application/json | Header `Content-Type` of the response.                                                 |
| response_example | string  | False    |                  | Body of the response, support use variables, like `$remote_addr $consumer_name`.       |
| response_schema  | object  | False    |                  | The JSON schema object for the response. Works when `response_example` is unspecified. |
| with_mock_header | boolean | False    | true             | When set to `true`, adds a response header `x-mock-by: APISIX/{version}`.              |
| response_headers | object  | false    |                  | Headers to be added in the mocked response. Example: `{"X-Foo": "bar", "X-Few": "baz"}`|

The JSON schema supports the following types in their fields:

- `string`
- `number`
- `integer`
- `boolean`
- `object`
- `array`

Here is a JSON schema example:

```json
{
    "properties":{
        "field0":{
            "example":"abcd",
            "type":"string"
        },
        "field1":{
            "example":123.12,
            "type":"number"
        },
        "field3":{
            "properties":{
                "field3_1":{
                    "type":"string"
                },
                "field3_2":{
                    "properties":{
                        "field3_2_1":{
                            "example":true,
                            "type":"boolean"
                        },
                        "field3_2_2":{
                            "items":{
                                "example":155.55,
                                "type":"integer"
                            },
                            "type":"array"
                        }
                    },
                    "type":"object"
                }
            },
            "type":"object"
        },
        "field2":{
            "items":{
                "type":"string"
            },
            "type":"array"
        }
    },
    "type":"object"
}
```

This is the response generated by the Plugin from this JSON schema:

```json
{
    "field1": 123.12,
    "field3": {
        "field3_1": "LCFE0",
        "field3_2": {
            "field3_2_1": true,
            "field3_2_2": [
                155,
                155
            ]
        }
    },
    "field0": "abcd",
    "field2": [
        "sC"
    ]
}
```

## Enable Plugin

The example below configures the `mocking` Plugin for a specific Route:

:::note
You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:

```bash
admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
```

:::

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/index.html",
    "plugins": {
        "mocking": {
            "delay": 1,
            "content_type": "application/json",
            "response_status": 200,
            "response_schema": {
               "properties":{
                   "field0":{
                       "example":"abcd",
                       "type":"string"
                   },
                   "field1":{
                       "example":123.12,
                       "type":"number"
                   },
                   "field3":{
                       "properties":{
                           "field3_1":{
                               "type":"string"
                           },
                           "field3_2":{
                               "properties":{
                                   "field3_2_1":{
                                       "example":true,
                                       "type":"boolean"
                                   },
                                   "field3_2_2":{
                                       "items":{
                                           "example":155.55,
                                           "type":"integer"
                                       },
                                       "type":"array"
                                   }
                               },
                               "type":"object"
                           }
                       },
                       "type":"object"
                   },
                   "field2":{
                       "items":{
                           "type":"string"
                       },
                       "type":"array"
                   }
               },
               "type":"object"
           }
        }
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'
```

## Example usage

Once you have configured the Plugin as mentioned above, you can test the Route.

The example used here uses this mocked response:

```json
{
  "delay":0,
  "content_type":"",
  "with_mock_header":true,
  "response_status":201,
  "response_example":"{\"a\":1,\"b\":2}"
}
```

Now to test the Route:

```shell
curl http://127.0.0.1:9080/test-mock -i
```

```
HTTP/1.1 201 Created
...
Content-Type: application/json;charset=utf8
x-mock-by: APISIX/2.10.0
...

{"a":1,"b":2}
```

## Delete Plugin

To remove the `mocking` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.

```shell
curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/index.html",
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'
```
