An API is a communication interface between different applications, allowing data exchange. It is accessed by sending a request that represents a data transmission. Then, the API validates it and performs the operation. Finally, it issues a response (success or error).
Azure’s API management tool is Azure API Management (APIM). It offers a several policies that enable various actions (modification, validation, etc.) upon receiving a request or before sending a response. In this article, we will focus on the validate-content and validate-parameters policies, which ensure that incoming data conforms to expectations before being processed. This involves controlling both the request and its content.
We will explain how these policies work and how to implement them through common use cases.
A basic knowledge of APIM is essential for this tutorial.
At least, I recommend watching Microsoft’s introduction video: https://www.youtube.com/watch?v=QdAWMNxvKe8 before continuing.
You also need an active Azure subscription and an APIM instance.
The validate-content policy is used to validate the size or content of the request body sent to the API. This policy should be placed in the “inbound” section of your API.
For more details, refer to Microsoft’s documentation on the topic: https://learn.microsoft.com/en-us/azure/api-management/validate-content-policy.
Let’s explore the main issues you may encounter and how to use policies to handle them.
This case demonstrates the use of the validate-content policy to check for the content type of the body. It is used when the processing in APIM (or after) depends on input data to perform the desired operation. You can ensure that the data format matches what is expected.
Here, we take the case where data needs to be provided in JSON format. We stop the processing in one of two cases:
Using the policy:
<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>
Explanation:
« validate-content »: refers to the policy used.
« unspecified-content-type-action=’prevent’ »: if the content type is not specified in the headers, the processing is blocked.
« max-size=’102400′ »: this is the maximum size of the request body in bytes.
« size-exceeded-action=’prevent’ »: if the request body exceeds the maximum size, the processing is blocked. The request cannot be processed.
« errors-variable-name=’requestBodyValidation’ »: validation errors are stored in the “requestBodyValidation” variable. This variable can be used in subsequent policies.
« content type=’application/json’ »: the header must be of type JSON. You can also use XML (application/xml) or SOAP (application/soap+xml) types.
« validate-as=’json’ »: the validation engine to be used is JSON since we are working with a JSON request. It can also be “xml” or “soap”.
« action=’prevent’ »: if the incoming request is not in JSON format, the processing is blocked.
To go further, an additional check can ensure that the incoming data conforms to a specific schema.
Using the policy:
To do this, you must create a schema in APIM and then add the schema-id="myschema" attribute, which gives us:
<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="myschema" />
</validate-content>
If the request body does not conform to the schema, APIM will automatically generate an error response (400). The response message will provide details about the non-compliance.
The validate-parameters policy allows you to validate:
For more details, refer to Microsoft’s documentation on the topic: https://learn.microsoft.com/en-us/azure/api-management/validate-parameters-policy.
We will explore the main issues you may encounter and how to use policies to handle them.
This case shows how to use the validate-parameters policy. It ensures that the parameters sent in the request (query parameters, path parameters, or headers) match what is expected for the APIM processing. If not, it might be better to stop the processing.
Using the policy:
<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="ignore" errors-variable-name="requestParametersValidation" />
Explanation:
« validate-parameters »: refers to the policy used.
« specified-parameter-action=’prevent’ »: processing is blocked if one or more expected parameters (configured at the operation level) are missing.
« unspecified-parameter-action=’ignore’ »: if extra parameters (not configured at the operation level) are present, no error is generated. In some cases, you may want to reject the request if extra parameters are specified.
« errors-variable-name=’requestParametersValidation’ »: validation errors are stored in the “requestParametersValidation” variable.
To go further, it’s possible to check for the presence of a specific parameter. If it’s missing, the request is blocked.
Using the policy:
<validate-parameters specified-parameter-action="ignore" unspecified-parameter-action="ignore" errors-variable-name="requiredParametersValidation">
<query specified-parameter-action="ignore" unspecified-parameter-action="ignore">
<parameter name="partnerCode" action="prevent" />
</query>
</validate-parameters>
Explanation:
« query »: section dedicated to the validation of query parameters.
« specified-parameter-action=’ignore’ » and « unspecified-parameter-action=’ignore’ »: by default, the system performs no special action for specified or unspecified query parameters.
« parameter name=’partnerCode’ action=’prevent’ »: the required parameter is “partnerCode”. The “prevent” action blocks the request if this parameter is not present.
In this case, we have applied the check to a query parameter (using the tag), but it’s also possible to do the same for a path parameter (using the tag) or a header (using the tag).
We have now seen how to control the data that APIM receives, illustrating it with a few use cases, but the possibilities for validation are extensive. You should refer to Microsoft’s documentation to build the policy suited to your needs.
This is a crucial step in managing APIM for two reasons. First, to ensure that the processing is carried out under the right conditions. Second, so that the client receives clear feedback about any non-compliance in their request.
Stopping the processing early can also save processing time and API usage.
In summary, the validate-content and validate-parameters policies in APIM embody the idea that “prevention is better than cure.”