request-validation
Summary#
Name#
request-validation plugin validates the requests before forwarding to an upstream service. The validation plugin uses
json-schema to validate the schema. The plugin can be used to validate the headers and body data.
For more information on schema, refer to JSON schema for more information.
Attributes#
Note that at least one of
header_schemaandbody_schemamust be filled in.
| Name | Type | Requirement | Default | Valid | Description |
|---|---|---|---|---|---|
| header_schema | object | optional | schema for the header data | ||
| body_schema | object | optional | schema for the body data | ||
| rejected_msg | string | optional | the custom rejected message |
How To Enable#
Create a route and enable the request-validation plugin on the route:
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 } }}'Test Plugin#
curl --header "Content-Type: application/json" \ --request POST \ --data '{"boolean-payload":true,"required_payload":"hello"}' \ http://127.0.0.1:9080/getIf the schema is violated the plugin will yield a 400 bad request with the reject response.
Disable Plugin#
Remove the corresponding json configuration in the plugin configuration to disable the request-validation.
APISIX plugins are hot-reloaded, therefore no need to restart APISIX.
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 } }}'Examples:#
Enum validate:
{ "body_schema": { "type": "object", "required": ["required_payload"], "properties": { "enum_payload": { "type": "string", "enum": ["enum_string_1", "enum_string_2"], "default": "enum_string_1" } } }}Boolean validate:
{ "body_schema": { "type": "object", "required": ["bool_payload"], "properties": { "bool_payload": { "type": "boolean", "default": true } } }}Number or Integer validate:
{ "body_schema": { "type": "object", "required": ["integer_payload"], "properties": { "integer_payload": { "type": "integer", "minimum": 1, "maximum": 65535 } } }}String validate:
{ "body_schema": { "type": "object", "required": ["string_payload"], "properties": { "string_payload": { "type": "string", "minLength": 1, "maxLength": 32 } } }}Regex validate:
{ "body_schema": { "type": "object", "required": ["regex_payload"], "properties": { "regex_payload": { "type": "string", "minLength": 1, "maxLength": 32, "pattern": "[[^[a-zA-Z0-9_]+$]]" } } }}Array validate:
{ "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] } } }}Multi-field combination verification:
{ "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 rejected 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 } }}