Mocking - Plugin - v3.4.x

古いプラグインバージョンのドキュメントを閲覧しています。

Looking for the plugin's configuration parameters? You can find them in the Mocking configuration reference doc.

Provide mock endpoints to test your APIs in development against your services. The Mocking plugin leverages standards based on the Open API Specification (OAS) for sending out mock responses to APIs. Mocking supports both Swagger 2.0 and OpenAPI 3.0.

Benefits of service mocking with the Kong Mocking plugin:

Conforms to a design-first approach since mock responses are within OAS.
Accelerates development of services and APIs.
Promotes parallel development of APIs across distributed teams.
Easily enable and disable the Mocking plugin for flexibility when testing API behavior.
Provides an enhanced full lifecycle API development experience with Dev Portal integration.

This plugin can mock 200, 201, and 204 responses.

Note: The plugin requires a spec to work. Depending on the Kong Gateway deployment mode, set either the api_specification_filename or the api_specification parameter.

Behavioral Headers

Behavioral headers allow you to change the behavior of the Mocking plugin for the individual request without changing the configuration.

X-Kong-Mocking-Delay

The X-Kong-Mocking-Delay header tells the plugin how many milliseconds to delay before responding. The delay value must be between 0(inclusive) and 10000(inclusive), otherwise it returns a 400 error.

HTTP/1.1 400 Bad Request

{
    "message": "Invalid value for X-Kong-Mocking-Delay. The delay value should between 0 and 10000ms"
}

X-Kong-Mocking-Example-Id

The X-Kong-Mocking-Example-Id header tells the plugin which response example is used when the endpoint has multiple examples for a single status code.

OpenAPI 3.0 allows you to define multiple examples in a single MIME type. The following example has two candidate examples: Hao and Sasha.

paths:
  /query_user:
    get:
      responses:
        '200':
          description: A user object.
          content:
            application/json:
              examples:
                Hao:
                  value:
                    id: 10
                    name: Hao
                Sasha:
                  value:
                    id: 20
                    name: Sasha

Makes a request to choose a specific example to respond to:

curl -X GET http://HOSTNAME:8000/query_user -H "X-Kong-Mocking-Example-Id: Sasha"

Response:

{
    "id": 20,
    "name": "Sasha"
}

X-Kong-Mocking-Status-Code

By default, the plugin chooses the minimum status code that is defined in the corresponding method.

The X-Kong-Mocking-Status-Code header allows requests to change the default status code selection behavior by specifying a status code that is defined in the corresponding method.

paths:
  /ping:
    get:
      responses:
        '200':
          description: '200'
          content:
            application/json:
              example:
                message: '200'
        '500':
          description: '500'
          content:
            application/json:
              example:
                message: '500'

Makes a request to choose a specific status code to respond to:

curl -i -X GET http://HOSTNAME:8000/ping -H "X-Kong-Mocking-Status-Code: 500"

Response:

HTTP/1.1 500 Internal Server Error

{
    "message": "500"
}

Tutorial Example

This example tutorial steps you through testing a mock response for a stock quote service API.

Note: Before following the steps in this tutorial, you can view a video demonstration of the Mocking plugin used in conjunction with the Dev Portal. See the Service Mocking video demo available on YouTube.

Prerequisites:

Kong Gateway Enterprise environment with the Dev Portal enabled on at least one workspace. See enable the Dev Portal using kong.conf. Also refer to the instructions for your environment:
An Open API Specification (yaml or json) that has at least one API method with an embedded example response. Multiple examples within a spec are supported. See the Stock API spec example.

Note: The spec must contain 200, 201, or 204 responses. The Mocking plugin doesn’t support any other response status codes.

Tutorial steps:

Deploy the example OAS spec that contains mocked responses to the Dev Portal or Insomnia.
Create the Stock service.
Create the get stock quote route.
Enable the Mocking plugin on the get stock quote route.
Enable the CORS plugin on the get stock quote route.
Test the mocked response from the Dev Portal, Insomnia, or the command line.
When you’ve completed your API mock testing, disable the Mocking plugin and update the service URL.

Step 1. Deploy the Stock API example spec

Deploy the Stock API spec example to either the Dev Portal or Insomnia.

Deploy a spec to the Dev Portal

Follow these steps to deploy a spec to the Dev Portal using Kong Manager. You can copy and paste the stock-01.json example file into the Dev Portal using Editor Mode.

Dev Portal Specs

Open Editor Mode and click New File.
Name the file stock-01.json.
Copy and paste the contents in the example into the new file.

Alternatively, you can also use the Portal Files API to upload a spec to the Dev Portal.

Deploy a spec to Insomnia

From the Insomnia dashboard, click Create > Import from File and select the stock-0.1.json file.
Click Design Document, then click OK on the success message.
(Optional) Click Deploy to Portal to deploy the spec to the Dev Portal.

Stock API spec example

The mocked responses in the example Stock spec stock-0.1.json are between lines 38 to 59 for GET stock/historical, and from lines 86 to 103 for GET stock/closing.

If applicable to your environment, replace the host entry in the spec with your IP address or URL for Kong Gateway.

{"swagger": "2.0",
    "info" : {
        "title": "Stock API",
        "description": "Stock Information Service",
        "version": "0.1"
    },
    "host": "127.0.0.1:8000",
    "basePath": "/",
    "schemes": [
        "http",
        "https"
    ],
    "consumes": [
        "application/json"
    ],
    "produces": [
        "application/json"
    ],
    "paths": {
       "/stock/historical": {
            "get": {
                "description": "",
                "operationId": "GET /stock/historical",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Production"
                ],
                "parameters": [
                    {
                        "required": true,
                        "in": "query",
                        "name": "tickers",
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status 200",
                        "examples": {
                            "application/json":
                                  {
                                "meta_data" : {
                                  "api_name" : "historical_stock_price_v2",
                                  "num_total_data_points" : 1,
                                  "credit_cost" : 10,
                                  "start_date" : "yesterday",
                                  "end_date" : "yesterday"
                                },
                                "result_data" : {
                                  "AAPL" : [ {
                                    "date" : "2000-04-23",
                                    "volume" : 33,
                                    "high" : 100.75,
                                    "low" : 100.87,
                                    "adj_close" : 275.03,
                                    "close" : 100.03,
                                    "open" : 100.87
                                  } ]
                                }
                              }
                            }
                          }
                }
           }
       },
     "/stock/closing": {
            "get": {
                "description": "",
                "operationId": "GET /stock/closing",
                "produces": [
                    "application/json"
                ],
                "tags": [
                    "Beta"
                ],
                "parameters": [
                    {
                        "required": true,
                        "in": "query",
                        "name": "tickers",
                        "type": "string"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Status 200",
                        "examples": {
                            "application/json":
                                  {
                                "meta_data" : {
                                  "api_name" : "closing_stock_price_v1"
                                },
                                "result_data" : {
                                  "AAPL" : [ {
                                    "date" : "2000-06-23",
                                    "volume" : 33,
                                    "high" : 100.75,
                                    "low" : 100.87,
                                    "adj_close" : 275.03,
                                    "close" : 100.03,
                                    "open" : 100.87
                                  } ]
                                }
                              }
                            }
                          }
                }
           }
       }
    }
}

Create the stock service

This example creates a service named Stock-Service.

curl -i -X POST http://localhost:8001/services \
  --data name=Stock-Service \
  --data url='https://httpbin.konghq.com/anything'

Response:

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: http://localhost:8002
Connection: keep-alive
Content-Length: 362
Content-Type: application/json; charset=utf-8
Date: Fri, 23 Apr 2021 14:16:42 GMT
Server: kong/2.4.0.0-beta1-enterprise-edition
X-Kong-Admin-Latency: 28
X-Kong-Admin-Request-ID: a4WLWEHkurc5IjKSZO2fy8GPmWd6ffs0
vary: Origin

{
    "ca_certificates": null,
    "client_certificate": null,
    "connect_timeout": 60000,
    "created_at": 1619187402,
    "host": "httpbin",
    "id": "94d95e04-bb28-4707-bef7-32307091b5dc",
    "name": "Stock-Service",
    "path": "/anything",
    "port": 80,
    "protocol": "http",
    "read_timeout": 60000,
    "retries": 5,
    "tags": null,
    "tls_verify": null,
    "tls_verify_depth": null,
    "updated_at": 1619187402,
    "write_timeout": 60000
}

Create the get stock quote route

This example creates a route named getStockQuote on the service named Stock-Service.

curl -X POST http://localhost:8001/services/Stock-Service/routes \
    --data "name=getStockQuote" \
    --data paths="/stock/historical"

Response:

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: http://localhost:8002
Connection: keep-alive
Content-Length: 497
Content-Type: application/json; charset=utf-8
Date: Fri, 23 Apr 2021 14:26:44 GMT
Server: kong/2.4.0.0-beta1-enterprise-edition
X-Kong-Admin-Latency: 29
X-Kong-Admin-Request-ID: UtF0twm9PoeI3gD7SqH6XDvm3JRqKm8o
vary: Origin

{
    "created_at": 1619188004,
    "destinations": null,
    "headers": null,
    "hosts": null,
    "https_redirect_status_code": 426,
    "id": "5ada3c98-c732-4c05-903f-9ba8ef026776",
    "methods": null,
    "name": "getStockQuote",
    "path_handling": "v0",
    "paths": [
        "/stock/historical"
    ],
    "preserve_host": false,
    "protocols": [
        "http",
        "https"
    ],
    "regex_priority": 0,
    "request_buffering": true,
    "response_buffering": true,
    "service": {
        "id": "94d95e04-bb28-4707-bef7-32307091b5dc"
    },
    "snis": null,
    "sources": null,
    "strip_path": true,
    "tags": null,
    "updated_at": 1619188004
}

Enable the Mocking plugin

This example enables the Mocking plugin on the getStockQuote route.

curl -X POST http://localhost:8001/routes/getStockQuote/plugins \
    --data "name=mocking"  \
    --data "config.api_specification_filename=stock-0.1.json"

Optional configuration for random simulated delay:

curl -X POST http://localhost:8001/routes/getStockQuote/plugins \
    --data "name=mocking"  \
    --data "config.api_specification_filename=stock-0.1.json" \
    --data "config.random_delay=true" \
    --data "config.max_delay_time=1" \
    --data "config.min_delay_time=0.001"

DB-less or hybrid mode configuration must use config.api_specification:

curl -X POST http://localhost:8001/routes/getStockQuote/plugins \
    --data "name=mocking"  \
    --data "config.api_specification=<spec_contents>"

Because a spec can be rather lengthy to put into a command, use a local variable to post a spec:

mock_ex=$(cat example.yaml); \
curl -X POST http://localhost:8001/routes/<route_id>/plugins \
  --data name=mocking \
  --data config.api_specification="$mock_ex"

In Kong Manager, you can copy and paste the contents of the spec directly into the Config.Api Specification text field.

Kong Manager Config API Spec Text Field

Response (random delay not enabled):

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: http://localhost:8002
Connection: keep-alive
Content-Length: 387
Content-Type: application/json; charset=utf-8
Date: Fri, 23 Apr 2021 20:40:51 GMT
Server: kong/2.4.0.0-beta1-enterprise-edition
X-Kong-Admin-Latency: 1510
X-Kong-Admin-Request-ID: iCZdp9JsqWhtmGLStICwBcOY4jT2R391
vary: Origin

{
    "config": {
        "api_specification": null,
        "api_specification_filename": "stock-0.1.json",
        "max_delay_time": 1,
        "min_delay_time": 0.001,
        "random_delay": false
    },
    "consumer": null,
    "created_at": 1619210451,
    "enabled": true,
    "id": "0d8ed6f6-6a4f-43df-8d81-980b5d9b2c7a",
    "name": "mocking",
    "protocols": [
        "grpc",
        "grpcs",
        "http",
        "https"
    ],
    "route": {
        "id": "5ada3c98-c732-4c05-903f-9ba8ef026776"
    },
    "service": null,
    "tags": null
}

Response (random delay enabled):

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: http://localhost:8002
Connection: keep-alive
Content-Length: 386
Content-Type: application/json; charset=utf-8
Date: Tue, 11 May 2021 14:50:19 GMT
Server: kong/2.4.0.0-beta1-enterprise-edition
X-Kong-Admin-Latency: 15
X-Kong-Admin-Request-ID: 2ZPP5GE3T6vL2bhbLRL7PBA2u9zgUEB8
vary: Origin

{
    "config": {
        "api_specification": null,
        "api_specification_filename": "stock-0.1.json",
        "max_delay_time": 1,
        "min_delay_time": 0.001,
        "random_delay": true
    },
    "consumer": null,
    "created_at": 1620744619,
    "enabled": true,
    "id": "273edea0-477a-4d9c-bb00-1cf99e48f191",
    "name": "mocking",
    "protocols": [
        "grpc",
        "grpcs",
        "http",
        "https"
    ],
    "route": {
        "id": "b0fad1db-eedf-4e1c-ace3-a394a640a514"
    },
    "service": null,
    "tags": null
}

Enable the CORS plugin

Cross-origin resource sharing (CORS) is disabled by default for security reasons. To test the mock response from the Dev Portal, enable the CORS plugin on the getStockQuote route.

curl -X POST http://localhost:8001/routes/getStockQuote/plugins \
    --data "name=cors"  \
    --data "config.origins=*"

Response:

HTTP/1.1 201 Created
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: http://localhost:8002
Connection: keep-alive
Content-Length: 449
Content-Type: application/json; charset=utf-8
Date: Fri, 23 Apr 2021 20:46:25 GMT
Server: kong/2.4.0.0-beta1-enterprise-edition
X-Kong-Admin-Latency: 10
X-Kong-Admin-Request-ID: niWS3bFPIUeHOfbLkQTQLS3qeIxSVoPx
vary: Origin

{
   "config": {
       "credentials": false,
       "exposed_headers": null,
       "headers": null,
       "max_age": null,
       "methods": [
           "GET",
           "HEAD",
           "PUT",
           "PATCH",
           "POST",
           "DELETE",
           "OPTIONS",
           "TRACE",
           "CONNECT"
       ],
       "origins": [
           "*"
       ],
       "preflight_continue": false
   },
   "consumer": null,
   "created_at": 1619210785,
   "enabled": true,
   "id": "4573e790-b0b5-4535-a1ab-88c42ca56f69",
   "name": "cors",
   "protocols": [
       "grpc",
       "grpcs",
       "http",
       "https"
   ],
   "route": {
       "id": "5ada3c98-c732-4c05-903f-9ba8ef026776"
   },
   "service": null,
   "tags": null
}

Test the mock response

Test the mocked response from within the Dev Portal Service, Insomnia, or from the command line.

Dev Portal mock spec test

Test the mock response from within the Dev Portal spec using the Try it out feature.

From the Dev Portal home page, click the Stock API Service tile.
Click the GET /stock/historical method and the Try it out button.
Enter the ticker sign AAPL in the tickers box and click Execute to see the server response.

Insomnia mock spec test

Test the mock response from within the Insomnia spec using the Try it out feature.

From the Insomnia dashboard, click the Stock API 0.1 Document tile.
Click the GET /stock/historical method and the Try it out button.
Enter the ticker sign AAPL in the tickers box and click Execute to see the server response.

Command line test

curl -X GET "http://localhost:8000/stock/historical?tickers=AAPL" \
  -H "accept: application/json"

The response matches the mocked response from within the spec:

HTTP/1.1 200 OK
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Length: 279
Content-Type: application/json; charset=utf-8
Date: Wed, 05 May 2021 19:59:06 GMT
Server: kong/2.4.0.0-beta1-enterprise-edition
X-Kong-Mocking-Plugin: true
X-Kong-Response-Latency: 40
vary: Origin

{
    "meta_data": {
        "api_name": "historical_stock_price_v2",
        "credit_cost": 10,
        "end_date": "yesterday",
        "num_total_data_points": 1,
        "start_date": "yesterday"
    },
    "result_data": {
        "AAPL": [
            {
                "adj_close": 275.03,
                "close": 100.03,
                "date": "2000-04-23",
                "high": 100.75,
                "low": 100.87,
                "open": 100.87,
                "volume": 33
            }
        ]
    }
}

Disable the Mocking plugin and update the Service URL

When your API mock testing is completed, disable the Mocking plugin and update the service URL.

Disable the Mocking plugin either in Kong Manager by clicking Disable for the plugin, or by using a command. You can copy and paste the plugin ID from within Kong Manager.

Copy Plugin ID

curl -X PATCH http://localhost:8001/plugins/<plugin-id>  -i \
    --data "name=mocking"  \
    --data "enabled=false"

Response:

HTTP/1.1 200 OK
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: http://localhost:8002
Connection: keep-alive
Content-Length: 347
Content-Type: application/json; charset=utf-8
Date: Fri, 07 May 2021 18:18:11 GMT
Server: kong/2.4.0.0-beta1-enterprise-edition
X-Kong-Admin-Latency: 11
X-Kong-Admin-Request-ID: 0s7xacYAUBFIY0LPanSkobV8mSdhOSvk
vary: Origin
{
    "config": {
        "api_specification": null,
        "api_specification_filename": "stock-0.1.json",
        "max_delay_time": 1,
        "min_delay_time": 0.001,
        "random_delay": false
    },
    "consumer": null,
    "created_at": 1620403609,
    "enabled": false,
    "id": "9a7dbe34-da00-47df-9939-5787abf2d3a1",
    "name": "mocking",
    "protocols": [
        "grpc",
        "grpcs",
        "http",
        "https"
    ],
    "route": null,
    "service": null,
    "tags": null
}

The enabled config reflects false in line 22.

The service URL can be anything for purposes of mocking. After you disable the Mocking plugin, ensure you set the actual URL for your service so that the response can be received.

Set Real Service URL

Behavioral Headers

X-Kong-Mocking-Delay

X-Kong-Mocking-Example-Id

X-Kong-Mocking-Status-Code

Tutorial Example

Step 1. Deploy the Stock API example spec

Deploy a spec to the Dev Portal

Deploy a spec to Insomnia

Stock API spec example

Create the stock service

Create the get stock quote route

Enable the Mocking plugin

Enable the CORS plugin

Test the mock response

Dev Portal mock spec test

Insomnia mock spec test

Command line test

Disable the Mocking plugin and update the Service URL

See also