Skip to main content
Version: 2.14

request-validation

Description#

The request-validation Plugin can be used to validate the requests before forwarding them to an Upstream service. This Plugin uses JSON Schema for validation and can be used to validate the headers and body of the request.

Attributes#

NameTypeRequiredDefaultValid valuesDescription
header_schemaobjectFalseSchema for the request header data.
body_schemaobjectFalseSchema for the request body data.
rejected_codeintegerFalse400[200,...,599]Status code to show when the request is rejected.
rejected_msgstringFalseMessage to show when the request is rejected.
note

At least one of header_schema or body_schema should be filled in.

Enabling the Plugin#

You can configure the Plugin on a specific Route as shown below:

curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
"request-validation": {
"body_schema": {
"type": "object",
"required": ["required_payload"],
"properties": {
"required_payload": {"type": "string"},
"boolean_payload": {"type": "boolean"}
},
"rejected_msg": "customize reject message"
}
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:8080": 1
}
}
}'

The examples below shows how you can configure this Plugin for different validation scenarios:

Enum validation:

{
"body_schema": {
"type": "object",
"required": ["required_payload"],
"properties": {
"enum_payload": {
"type": "string",
"enum": ["enum_string_1", "enum_string_2"],
"default": "enum_string_1"
}
}
}
}

Boolean validation:

{
"body_schema": {
"type": "object",
"required": ["bool_payload"],
"properties": {
"bool_payload": {
"type": "boolean",
"default": true
}
}
}
}

Number or Integer validation:

{
"body_schema": {
"type": "object",
"required": ["integer_payload"],
"properties": {
"integer_payload": {
"type": "integer",
"minimum": 1,
"maximum": 65535
}
}
}
}

String validation:

{
"body_schema": {
"type": "object",
"required": ["string_payload"],
"properties": {
"string_payload": {
"type": "string",
"minLength": 1,
"maxLength": 32
}
}
}
}

Regular expression validation:

{
"body_schema": {
"type": "object",
"required": ["regex_payload"],
"properties": {
"regex_payload": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"pattern": "[[^[a-zA-Z0-9_]+$]]"
}
}
}
}

Array validation:

{
"body_schema": {
"type": "object",
"required": ["array_payload"],
"properties": {
"array_payload": {
"type": "array",
"minItems": 1,
"items": {
"type": "integer",
"minimum": 200,
"maximum": 599
},
"uniqueItems": true,
"default": [200, 302]
}
}
}
}

Combined validation:

{
"body_schema": {
"type": "object",
"required": ["boolean_payload", "array_payload", "regex_payload"],
"properties": {
"boolean_payload": {
"type": "boolean"
},
"array_payload": {
"type": "array",
"minItems": 1,
"items": {
"type": "integer",
"minimum": 200,
"maximum": 599
},
"uniqueItems": true,
"default": [200, 302]
},
"regex_payload": {
"type": "string",
"minLength": 1,
"maxLength": 32,
"pattern": "[[^[a-zA-Z0-9_]+$]]"
}
}
}
}

Custom rejection message:

{
"uri": "/get",
"plugins": {
"request-validation": {
"body_schema": {
"type": "object",
"required": ["required_payload"],
"properties": {
"required_payload": {"type": "string"},
"boolean_payload": {"type": "boolean"}
},
"rejected_msg": "customize reject message"
}
}
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:8080": 1
}
}
}

Example usage#

Once you have configured the Plugin, it will only allow requests that are valid based on the configuration to reach the Upstream service. If not, the requests are rejected with a 400 or a custom status code you configured.

A valid request for the above configuration could look like this:

curl --header "Content-Type: application/json" \
--request POST \
--data '{"boolean-payload":true,"required_payload":"hello"}' \
http://127.0.0.1:9080/get

Disable Plugin#

To disable the request-validation 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.

curl http://127.0.0.1:9080/apisix/admin/routes/5 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri": "/get",
"plugins": {
},
"upstream": {
"type": "roundrobin",
"nodes": {
"127.0.0.1:8080": 1
}
}
}'