Common usage of validate-content policy in APIM

Posted by

This post has been republished via RSS; it originally appeared at: New blog articles in Microsoft Community Hub.

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:

 

1.png

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.

2.png

 

3.png

 

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.

 

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable name="requestBodyValidation"> </validate-content>

 

4.png

5.png

 

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.

 

{ "required":[ "name" ], "type": "object", "properties": { "name": { "type": "string" }, "age": { "type": "integer" }, "paramobj": { "type": "object", "properties": { "color": { "type": "string" } } } } }

 

Then add the content element in the content validation

 

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation"> <content type="application/json" validate-as="json" action="prevent" /> </validate-content>

 

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

6.png

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

7.png

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:

8.png

1.5 Validate empty string or zero number

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

 

{ "required":[ "name" ], "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "age": { "type": "integer", "minimum": 1 }, "paramobj": { "type": "object", "properties": { "color": { "type": "string" } } } } }

 

9.png

10.png

1.6 Validate required nested property

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

 

{ "required": [ "name", "age", "paramobj" ], "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "age": { "type": "integer", "minimum": 1 }, "paramobj": { "required": [ "color" ], "type": "object", "properties": { "color": { "type": "string" } } } } }

 

11.png

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.

 

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation"> <content type="application/json" validate-as="json" action="prevent" allow-additional-properties = "false"/> </validate-content>

 

12.png

 

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.

13.png

14.png

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.

 

<validate-content unspecified-content-type-action="prevent" max-size="102400" size-exceeded-action="prevent" errors-variable-name="requestBodyValidation"> <content type="application/json" validate-as="json" action="prevent" schema-id="jayapimschema" /> </validate-content>

 

 

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.