In this blog post, we’ll have a close look at the validation policies in Azure API Management (APIM). You can use validation policies to validate API requests and responses against their OpenAPI spec directly in APIM and avoid calling your backend with incorrect data. This blog describes how to add the validation policies to your APIM policies and how to handle the exceptions. You can find the Microsoft documentation here.

There are four ways to validate request and responses, Content, Headers, Parameters, and Status Code. Three actions are possible: ignore will skip the validation, detect will log the validation error but not interrupt execution, while prevent will stop processing.

Content

The validate-content policy validates the size of a request or response and ensures that the body coming in or out follows the specification in the API description. For schema validation, we’re limited to JSON payload. Size validation works with all content types up to 100KB payload size. This validation can be applied on all scopes for sections inbound, outbound and on-error.

APIM will always return a status code 400 when a validation exception occurs.

Examples

Size exceeded:

Wrong Content-Type:

The Body doesn’t contain one or many required properties:

Parameters

The validate-parameters policy validates the header, query, or path parameters in requests against the API schema and is applicable. As it is only for requests, it is only applicable in the inbound section.

The policy structure is an override structure. On the validate-parameters you can specify settings for all parameters, all query, header, or path parameters specified. In the header, path, query section, you can override this for a specific type. And in the parameter section, you can do it for a specific parameter.

The specified-parameter-action checks all specified parameters. It checks if the value matches with the type specified and if the value exists in the case of an enum. The unspecified-parameter-action throws an exception when a parameter is added which is not specified in the OpenAPI specs.

Remark

The validate-parameters doesn’t check the required flag on a parameter.

In this case fe. https://yourapim.azure-api.net/yourapi won’t result in an error, although you marked the QueryParam as mandatory.

Examples

Wrong value in the Query parameter:

Unspecified Header added:

Response Headers

The validate-headers policy validates the response headers against the API schema. As it is only for responses, it is only applicable in the outbound and on-error section.

This is the counterpart of the validate-parameters/headers policy in the inbound section and it works in the same way concerning the specified and unspecified action.

Status Code

The validate-status-codepolicy checks if the status code your backend/APIM is responding to is defined in the OpenAPI specs. It is only applicable in the outbound and on-error sections.

Remark

The Status Code check is not returning a 400 error, but a 502.

Examples

Logging

As stated before, you have three possible actions which you can specify on a validation scope.

Ignore: The validation will be skipped;
Prevent: The request will be blocked and an error will be thrown;
Detect: The exception is logged, but the request continues.

How does logging work and where can you find the logs?

OCP-APIM-Trace

You can see all detections in the trace.

Application Insights and Log Analytics

When configured in APIM, it is also possible to see the detected errors in Application Insights and/or Log Analytics. You’ll have to trace the exception. As every exception is caught in a context variable, we can use this variable to trace.

The variable generated is of type List<OpenApiError>

LastError

When configured in a prevent action, a validation error blocks further request or response processing and is also propagated to the context.LastError property which you can use in the on-error section.

Conclusion

There is definitely an added value to making sure that all incoming request and outgoing responses are compliant with the OpenAPI specs and makes it possible to keep your api’s secure. Nevertheless, you’ll have to take into account the possible performance impact. Doing the validations in Azure API Management (APIM) has a performance impact. On the other side: when incorrect requests are blocked on the APIM level, it has a positive impact on your backend’s performance. It is up to you to find the right trade-off.