Une API est une interface de communication entre différentes applications permettant d’échanger des données. Elle est accessible en lui envoyant une requête qui représente une demande de transmission de données. Ensuite, l’API la valide et réalise l’opération. Enfin, elle émet à son tour une réponse (succès ou erreur).
L’outil de management d’APIs d’Azure est Azure API Management (APIM). Il met à disposition un certain nombre de policies permettant plusieurs actions (modification, validation, etc.) à la réception de la requête ou avant l’envoi de la réponse. Dans cet article, nous allons nous intéresser aux policies validate-content et validate-parameters qui permettent de vérifier que les données en entrée soient conformes aux attentes avant de les traiter. Pour réaliser cela, il s’agit de contrôler la requête ainsi que son contenu,
Nous allons expliquer le fonctionnement de ces policies et comment les mettre en place à l’aide de cas d’utilisation courants.
Une connaissance d’APIM est essentiel pour ce tutoriel.
A minima, je vous recommande de regarder la présentation de Microsoft : https://www.youtube.com/watch?v=QdAWMNxvKe8 avant de poursuivre la lecture.
Il convient également d’avoir un abonnement Azure actif ainsi qu’une instance APIM.
On utilise la policy validate-content dans le but de valider la taille ou le contenu du corps de la requête émise à l’API. Il convient de placer la policy dans la partie « inbound » de votre API.
Pour plus de détails, vous pouvez vous rapporter à la documentation Microsoft sur le sujet : https://learn.microsoft.com/fr-fr/azure/api-management/validate-content-policy.
Nous allons présenter les principaux problèmes que vous pouvez rencontrer et comment utiliser les policies pour les prendre en charge.
Ce cas présente l’utilisation de la policy validate-content pour contrôler la présence et le format des données. On l’utilise lorsque le traitement fait dans APIM (ou après) est dépendant de données en entrée afin réaliser l’opération voulue. On contrôle ainsi que le format de la donnée corresponde bien à ce qui est attendu.
Ici nous prenons le cas où il faut fournir des données au format JSON. Nous arrêtons le traitement dans l’un de ces deux cas :
Utilisation de la 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>
Explication :
« validate-content » : permet de faire référence à la policy utilisée.
« unspecified-content-type-action=’prevent’ » : si le type de contenu n’est pas spécifié dans les headers, alors on bloque le traitement.
« max-size=’102400′ » : il s’agit de la valeur maximale d’octets du corps de la requête.
« size-exceeded-action=’prevent’ » : si le corps de la requête dépasse la taille maximale alors on bloque le traitement. On ne peut pas prendre en charge la requête.
« errors-variable-name=’requestBodyValidation’ » : on enregistre les erreurs de validations dans la variable « requestBodyValidation ». Il est alors possible d’utiliser cette variable dans la suite des policies.
« content type=’application/json’ » : l’en-tête doit être de type JSON. Il est également possible d’avoir les types XML (application/xml) ou SOAP (application/soap+xml).
« validate-as=’json’ » : le moteur de validation à utiliser est JSON car nous sommes sur une requête json. Cela peut également être « xml » ou « soap ».
« action=’prevent’ » : si la requête entrante n’est pas au format JSON, on bloque le traitement.
Pour aller plus loin, un contrôle supplémentaire peut être de s’assurer que les données en entrée correspondent à un schéma spécifique.
Utilisation de la policy :
Pour ce faire, il faut créer un schéma dans APIM puis ajouter l’attribut schema-id="monschema" ce qui nous donne :
<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="monschema" />
</validate-content>
Si le corps de la requête ne correspond pas au schéma, APIM va automatiquement générer une réponse en erreur (400). Le message de la réponse contient des précisions sur la non-conformité rencontrée.
La policy validate-parameter permet de valider :
Pour plus de détails, vous pouvez vous rapporter à la documentation Microsoft sur le sujet : https://learn.microsoft.com/fr-fr/azure/api-management/validate-parameters-policy.
Nous allons présenter les principaux problèmes que vous pouvez rencontrer et comment utiliser les policies pour les prendre en charge.
Ce cas montre comment utiliser la policy validate-parameter. Elle permet de contrôler les paramètres envoyés par la requête (query parameters, path parameters ou headers) afin qu’ils correspondent aux attentes du traitement d’APIM. Si ce n’est pas le cas, il est peut-être préférable d’arrêter le traitement.
Utilisation de la policy :
<validate-parameters specified-parameter-action="prevent" unspecified-parameter-action="ignore" errors-variable-name="requestParametersValidation" />
Explication :
« validate-parameters » : permet de faire référence à la policy utilisée.
« specified-parameter-action=’prevent’ » : on bloque le traitement si un ou plusieurs paramètres attendus (configurés au niveau de l’opération) ne sont pas présents.
« unspecified-parameter-action=’ignore’ » : si des paramètres supplémentaires (non configurés au niveau de l’opération) sont présents, aucune erreur ne sera générée. Dans certains cas, on peut vouloir rejeter la requête si des paramètres supplémentaires sont spécifiés.
« errors-variable-name=’requestParametersValidation’ » : on enregistre les erreurs de validations dans la variable « requestParametersValidation ».
Pour aller plus loin, il est possible de contrôler la présence d’un paramètre spécifique. Si tel n’est pas le cas, on bloque la requête.
Utilisation de la 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>
Explication :
« query » : section dédiée à la validation des paramètres de la requête.
« specified-parameter-action=’ignore’ » et « unspecified-parameter-action=’ignore’ » : par défaut, le système n’effectue aucune action particulière pour les paramètres de requête spécifiés ou non spécifiés.
« parameter name=’partnerCode’ action=’prevent’ » : le paramètre requis est « partnerCode ». L’action « prevent » bloque la requête si ce paramètre n’est pas présent.
Ici, nous avons vu un cas appliqué à un query parameter (balise <query>), mais il est possible de faire la même chose avec un path parameter (balise <path>) ou un header (balise <headers>).
Ainsi, nous avons vu comment contrôler les données qu’APIM reçoit. Nous l’avons illustré avec quelques cas d’utilisation mais les possibilités de contrôle sont grandes. Il convient de se référer à la documentation Microsoft pour construire la policy adaptée à votre besoin.
C’est une étape indispensable à la bonne gestion d’APIM pour deux raisons. D’une part, pour que le traitement se fasse dans de bonnes conditions. D’autre part, afin que le client puisse avoir un retour clair sur la non-conformité de sa requête.
Ne pas poursuivre le traitement permet aussi de réaliser des économies de temps de traitement et de sollicitation de l’API.
En somme, les policies validate-content et validate-parameters correspondent dans APIM à l’expression « mieux vaut prévenir que guérir ».