Common usage of validate-content policy in APIM

This validate-content policy is very helpful while we need to validate the size or content of a request or response body against one or more supported schemas. In this blog, I would like to introduce how to use different Elements and Attributes in validate-content policy to implement multiple requirements of request payload based on JSON schema validation.

We will cover two sections below mostly:

1. Using API level schema definition to restrict request payload
2. Using Service level schema definition to restrict request payload

Section1: Using API level schema definition to restrict request payload

In some certain scenarios, we have existing schema definition already while importing the new API. 

If we don't have schema definition, we could use REST API or create schema definition in the APIM portal. Let’s say we have following schema definition:

Then we can navigate to the specific POST Operation design page to add requested content types and schemas. We shall see the schema definition created above in the DEFINITION drop-down box.

1.1 Validate content-type

Now, if we test the POST request directly without adding content-type http header or setting incorrect content-type header, it won’t be blocked as we haven’t set any content validation policy. Once we set following validate-content policy, the above request can be blocked.

we can notice that the unspecified-content-type-action attribute is set as prevent. In fact, we have following three actions for us to control the validate behavior. In the most situations, we need to block the request by using ‘prevent’. However, we only need to get warnings or validation log instead of blocking critical requests sometimes, thus we can use ‘detect’ action. Or we can skip the configured validation as we want.

• ignore   : Skip validation.
• prevent : Block the request or response processing, log the verbose validation error, and return an error. Processing is interrupted when the first set of errors is detected.
• detect   : Log validation errors, without interrupting request or response processing.

1.2 Validate request body size

In the above policy definition, we can also notice that the maximum length of the request body is also restricted in the bytes by using max-size attribute. The Content-Length header will be checked accordingly. If the request body or response body is compressed, this value is the decompressed length. Maximum allowed value: 102,400 bytes (100 KB). As same as content type, we support three actions regarding the validate behavior.

1.3 Validate required property

We can use following sub element content to validate if the detailed body payload matches the scheme definition. Let’s say we need to make sure the ‘name is required in the incoming request payload, we can add required parameter in the schema definition.

Please refer to more definition details from this OpenAPI 3.0 specification link.

Then add the content element in the content validation

If we give null value in the body payload, we will get error ‘Expected Object but got Undefined’

If we miss ‘name’ property, it’s blocked.

1.4 Validate property type

If we set the incorrect data type, the request will be blocked as well if we use prevent action. For example, we set integer value for the String property:

1.5 Validate empty string or zero number

We can restrict empty string by setting minLength > 0 in the scheme definition

1.6 Validate required nested property

We only need to set required array parameter in the nested JSON object or JSON array.

1.7 Block additional properties

In some certain situations, we don’t want to allow addition properties in the request payload which are not included in the schema definition. We can set allow-additional-properties as false to block additional properties.

• true: allow additional properties in the request or response body, even if the JSON schema's additionalProperties field is configured to not allow additional properties.
• false: do not allow additional properties in the request or response body, even if the JSON schema's additionalProperties field is configured to allow additional properties.

Please notice that if the attribute isn't specified, the policy validates additional properties according to configuration of the additionalProperties field in the schema.

Section2: Using service level schema definition to restrict request payload

Using the validate-content policy, we may optionally validate against one or more JSON or XML schemas that we’ve added to API Management instance and that aren't part of the API definition. A schema that we add to API Management can be reused across many APIs.

You could refer to this guidance to create scheme definition in the APIM service level.

If we set the schema-id as the service level schema definition, the validate-content will use service level schema definition for validation. If this property is not specified, default schema will be used.