ADC

Spécification de l’API d’importation

La spécification d’API définit la conception d’une API, y compris les points de terminaison, les méthodes, les paramètres et les formats de données. La fonctionnalité d’importation de spécifications d’API vous permet d’importer la spécification d’API ouverte, qui est généralement utilisée pour décrire l’API REST. Lorsque le Web App Firewall effectue un contrôle de validation sur la demande d’un utilisateur pour un service Web basé sur une API, il valide la demande par rapport au schéma spécifié dans le fichier de spécification de l’API pour ce service Web. NetScaler prend en charge les validations de schéma pour une API REST, la charge utile étant le JSON de l’application et ProtoBuf pour les requêtes d’API gRPC.

NetScaler prend en charge les formats de spécification suivants :

  • API ouverte - Swagger 2.0, OAS 3.0, 3.1
  • ProtoBuf - v3 et v2

Gestion des fichiers de spécifications d’API

Vous pouvez valider le trafic d’API entrant par rapport à la spécification d’API importée en l’attribuant à un profil et en définissant une règle de relaxation pour bloquer ou autoriser le trafic. L’importation d’une spécification d’API se déroule en deux étapes :

  1. Importer la spécification d’API : importez une spécification d’API dans NetScaler via une URL ou depuis le système.
  2. Ajouter la spécification d’API à NetScaler : lorsque vous ajoutez une spécification d’API à NetScaler, le fichier est validé, converti dans un format interne et une entité de spécification d’API est créée. L’entité de spécification d’API créée sera utilisée dans les expressions de stratégie et les profils Web App Firewall.

Remarque :

Assurez-vous que les fichiers de spécifications Open API Swagger 2.0, OAS 3.0 et 3.1 chargés ne contiennent aucune référence à des fichiers externes. Si vous devez utiliser les informations d’un fichier externe, consolidez les informations dans un seul fichier à l’aide d’outils open source, puis téléchargez-le.

Gérez les fichiers de spécifications d’API à l’aide de la CLI

Les paramètres suivants sont utilisés dans les commandes CLI :

  • Nom : nom du fichier de spécification d’API chargé.
  • Source : URL (protocole, hôte, chemin et nom) indiquant l’emplacement où stocker le fichier de spécifications importé.
  • Nom de la spécification - nom de l’entité créée à partir de la spécification d’API téléchargée.
  • Type : format d’entrée de la spécification de l’API. Valeur par défaut : OAS

Pour importer un fichier de spécification d’API, saisissez :

import api specFile <name> <src>

Exemple :
import apispec testapispec.json http://www.example.com/testapispec.json

Pour ajouter un fichier de spécification d’API, tapez :

add api spec <Name> -File <string> -Type <string>

Exemple :
add api spec testapispec -File testapispec.json -Type OAS

Pour mettre à jour un fichier de spécification d’API, importez un nouveau fichier de spécifications qui doit être mis à jour.

À l’invite de commandes, tapez :

update api spec <specName> -File <string> -Type <string>

Exemple :
update api spec testapispec -File testapispec.json -Type OAS

Remarque :

Si l’attribut type n’est pas spécifié, OAS est le type par défaut.

Pour afficher tous les points de terminaison, tapez :

show api spec <specName>

Exemple :

show api spec testapispec

Pour supprimer la spécification de l’API, tapez :

rm api spec <specName>

Exemple :

rm api spec testapispec

Remarque :

Avant de supprimer la spécification d’API, assurez-vous qu’elle n’est pas utilisée par un profil ou une stratégie.

Gérez les fichiers de spécifications d’API à l’aide de l’interface graphique

  1. Accédez à Sécurité > NetScaler Web App FirewallImportations.
  2. Sur la page Importations, sélectionnez l’onglet Page d’importation des spécifications API, puis cliquez sur Ajouter.
  3. Sur la page API Spec Import Object, sélectionnez l’une des options suivantes pour le paramètre Importer depuis :
    1. URL : URL Web d’un site Web accessible à l’appliance.
    2. Fichier : fichier sur un disque dur local ou en réseau ou sur un autre périphérique de stockage.
  4. Cliquez sur Continuer.
  5. Sur la page API Spec Import Object, entrez les informations suivantes :
    1. Nom de la spécification d’API : nom de l’entité créée à partir de la spécification d’API téléchargée. Remarque : le nom du fichier API et le nom de spécification de l’API saisis doivent être identiques.
    2. Type de spécification d’API : sélectionnez le type de spécification.

      Types : REST (OpenAPI/Swagger) et gRPC (PROTO).

      Type par défaut : REST (OpenAPI/Swagger)

    3. Cliquez sur Terminé.

L’entité nouvellement ajoutée est répertoriée sur la page Imports sous l’ onglet API Spec Import Page.

Afficher les statistiques des spécifications de l’API et des points de terminaison de l’API

Vous pouvez consulter les statistiques suivantes pour toutes les spécifications de l’API et les points de terminaison de l’API :

  • Hits liés aux spécifications de l’API : demandes correspondant à n’importe quel point de terminaison de la spécification de l’API.
  • Validations réussies des spécifications d’API : demandes correspondant à n’importe quel point de terminaison de la spécification d’API et conformes au schéma de l’API.
  • Demandes non concordantes relatives à la spécification de l’API : demandes ne correspondant à aucun point de terminaison de la spécification de l’API.
  • Accès aux points de terminaison de l’API : demandes correspondant à un point de terminaison spécifique.
  • Validations réussies des points de terminaison d’API : demandes correspondant à un point de terminaison spécifique et conformes au schéma de l’API.

Afficher les spécifications de l’API et les statistiques des terminaux d’API à l’aide de la CLI

À l’invite de commandes, tapez :

stat apispec <apispec name>

Exemple

stat apispec testapispec

Afficher les spécifications de l’API et les statistiques des terminaux d’API à l’aide de l’interface graphique

  1. Accédez à Sécurité > NetScaler Web App FirewallImportations.
  2. Sur la page Importations, sélectionnez l’onglet Importer des spécifications d’API, puis cliquez sur Statistiques.

    Le résumé des spécifications de l’API s’affiche.

  3. Pour afficher le résumé des points de terminaison, cliquez sur l’une des spécifications de l’API.

    Le résumé des points de terminaison de l’API s’affiche pour la spécification d’API sélectionnée.

Spécification de l’API d’importation