Skip to content
|
Plugin Hub
github-edit-pageEdit this page
report-issueReport an issue
header icon

Adding attributes to HTTP requests with Kong Gateway

By Kong Inc.
You are browsing unreleased documentation.

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 with curl 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 have jq or do not wish to install it, you can modify the commands to remove jq 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?