このページは、まだ日本語ではご利用いただけません。翻訳中です。
It’s very common to have an HTTP service which accepts requests expecting a JSON document in the body. Let’s assume that the development team of your service plans to change the request API in the near future, and will eventually begin to require a new field in the JSON body of the requests. Eventually your client applications will need to upgrade their requests to support this new value, but how could you provide a default value for your services in the meantime?
This guide will show you how to configure the Request Transformer plugin using the Kong Admin API to modify incoming requests with a static constant value. Then you will test the feature with a mock request to verify the transformation process.
Prerequisites
- This document is best used after following the companion Kong Gateway in minutes guide, which walks you through running a local Kong Gateway in Docker, setting up a mock service, and the necessary connection details. If you’d like to use an existing Kong Gateway or a different service, you will need to adjust the commands in this guide as necessary.
- You have
curl
installed on your system, which is used to send requests to the gateway. Most systems come withcurl
pre-installed. - This guide uses the
jq
command line JSON processing tool. While this tool is not necessary to complete the tasks, it’s helpful for processing JSON responses from the gateway. If you do not havejq
or do not wish to install it, you can modify the commands to removejq
processing.
Set up the Request Transformer plugin
Assign a new instance of the Request Transformer plugin to
the mock service by sending a POST
request to the Admin API.
In this command, the config.add.body
value instructs the plugin to add a new
field to the body of incoming requests before forwarding them to the mock
service.
In this example, we are instructing the plugin to add a field named new-field
and
give it a static value of defaultValue
.
curl -i -X POST $KONG_ADMIN_API/services/mock/plugins \
--data "name=request-transformer" \
--data "config.add.body=new-field:defaultValue"
If successful the API will return a 201 Created
HTTP response code with a
JSON body including information about the new plugin instance.
Next, use the mock
service’s /anything
endpoint to test the behavior of the plugin.
The /anything
API will echo back helpful information from the request we send it, including
headers and the request body.
curl -s -XPOST $KONG_PROXY/mock/anything \
-H 'Content-Type: application/json' \
-d '{"existing-field": "abc123"}'
The JSON response will contain the postData
field which includes the
JSON body sent to the service. You can use jq
to fully extract the request body
returned from the mock
service, as follows:
curl -s -XPOST $KONG_PROXY/mock/anything \
-H 'Content-Type: application/json' \
-d '{"existing-field": "Kong FTW!"}' | \
jq -r '.postData.text'
This will output the following text indicating new-field
has been added to the request body.
{"existing-field":"Kong FTW!","new-field":"defaultValue"}
What’s next?
- More advanced transformations can be accomplished with the Request Transformer Advanced plugin.
- If no standard plugin is available to satisfy your use case, the Plugin Development Guide can help you with developing your own plugin.