L’explorateur d’interface de protocole d’application

Utilisez l’explorateur d’interface de protocole d’application pour en apprendre davantage sur l’API REST. Vous pouvez également tester les différentes méthodes et ressources pour vérifier que vous les configurez correctement. Vous pouvez copier et coller les modèles JSON dans votre code comme point de départ.


Astuces

Le but de l’explorateur d’interface de protocole d’application est de vous aider à vous familiariser avec l’API. Pour tester des appels dans l’explorateur d’interface de protocole d’application, il faut créer des verrouillages d’accès qui pourraient interférer avec le fonctionnement normal de l’API. Nous vous recommandons d’utiliser l’explorateur d’interface de protocole d’application sur un dispositif hors production.

Ouvrir l’explorateur d’interface de protocole d’application

L’explorateur d’interface de protocole d’application explique toutes les ressources et les objets JSON disponibles à être utilisés en programmation. L’explorateur fournit des informations détaillées sur les paires attribut-valeur dans chaque objet, et vous pouvez tester les différentes méthodes HTTP pour vous assurer de bien comprendre le codage requis pour utiliser chaque ressource.

Procédure

Étape 1

À l’aide d’un navigateur, ouvrez la page d’accueil du système, par exemple, https://ftd.example.com.

Étape 2

Connectez-vous au gestionnaire d'appareil.

Étape 3

(6.4 et versions antérieures.) Modifiez l’URL pour qu’elle pointe vers /#/api-explorer, par exemple, https://ftd.example.com/#/api-explorer.

Étape 4

(6.5 et versions ultérieures.) Cliquez sur le bouton des autres options (bouton plus d'options.) et choisissez API Explorer (Explorateur d’interface de protocole d’application).

Le système ouvre l’explorateur d’interface de protocole d’application dans un onglet ou une fenêtre distincte, en fonction des paramètres de votre navigateur.

S’y retrouver dans l’explorateur d’interface de protocole d’application

Lorsque vous entrez dans l’explorateur d’interface de protocole d’application, une liste de groupes de ressources s’affiche. Ces groupes incluent les ressources disponibles dans l’API. L’illustration suivante montre un petit exemple de la liste.


Liste des ressources dans l’explorateur d’interface de protocole d’application.

Ces noms de groupes sont des liens : cliquez sur le lien pour ouvrir le groupe et voir les méthodes que vous pouvez utiliser avec les ressources de ce dernier. Chaque groupe comprend également les commandes suivantes à droite :

  • Show/Hide (Afficher/Masquer) ouvre et ferme le groupe. Cela revient à cliquer sur le nom du groupe. Au départ, cette action ne fait qu’afficher les méthodes (c’est-à-dire le même contenu que List Operations [Énumérer les opérations]), mais le système se souviendra du dernier niveau de développement de la liste (avant qu’elle ne soit fermée) et se rouvrira au même degré de développement.

  • List Operations (Énumérer les opérations) affiche les méthodes HTTP disponibles pour chaque ressource du groupe. Les informations comprennent le chemin relatif pour le modèle de localisateur de ressources universel (URL) pour chaque ressource. Les variables de chemin sont indiquées par la convention standard : {variable} . Vous devez remplacer {variable} , y compris les accolades, par une valeur appropriée. Vous devez ajouter l’URL de base à ce chemin relatif; voir L’URL de base pour l’API.

    Cliquez sur un modèle d’URL d’opération pour afficher la documentation complète sur cette méthode.

  • Expand Operations (Développer les opérations) ouvre toutes les méthodes et les ressources HTTP disponibles dans un groupe.

Certains groupes ont de nombreuses ressources enfants. Par exemple, le groupe DataInterface ManagementAccess comprend les opérations GET, POST et DELETE pour /devicesettings/default/managementaccess, ainsi que les opérations GET et PUT pour /devicesettings/default/managementaccess/{objId}.


Liste des ressources pour une catégorie dans l’explorateur d’interface de protocole d’application.

Consulter la documentation concernant une ressource

Les attributs de chaque ressource sont documentés dans l’explorateur d’interface de protocole d’application.

Procédure

Étape 1

Naviguez vers la ressource et la méthode qui vous intéressent.

Étape 2

Dans la section Response Class (Classe de réponse), cliquez sur l’onglet Model (Modèle).

Le modèle répertorie les attributs avec les descriptions et les types de données. Pour la méthode GET, il existe également des options de pagination qui peuvent être renvoyées. S’il y a plus d’objets que ceux renvoyés dans la réponse, vous obtenez les URL pour le lot d’objets suivant et le lot précédent.

Par exemple, le graphique suivant montre la méthode et la ressource POST /object/tcppports, avec l’onglet Model (Modèle) sélectionné. Par défaut, l’onglet Example Value (Valeur d’exemple) est sélectionné, vous devez donc toujours cliquer sur Model (Modèle) pour voir la documentation.


La documentation de POST object/tcpports dans l’explorateur d’interface de protocole d’application.

Trouver l’identifiant de l’objet (objId) et l’identifiant du parent (parentId)

Certaines ressources nécessitent un identifiant d’objet ou un identifiant d’objet parent associé dans l’URL, notamment les éléments suivants :

  • PUT /object/networks/{objId}

  • GET /policy/intrusionpolicies/{parentId}/intrusionrules

Dans la plupart des cas, vous pouvez obtenir l’identifiant de l’objet ou du parent en utilisant une méthode GET d’un niveau supérieur dans la hiérarchie des ressources. L’identifiant de l’objet ou du parent est l’UUID sur le paramètre id pour un objet donné.

Par exemple, GET /object/networks renvoie une liste de tous les objets réseau actuellement définis. Vous devrez peut-être effectuer plusieurs appels pour parcourir la liste et atteindre l’objet souhaité, ou inclure le paramètre de requête limit pour augmenter le nombre d’objets renvoyés par appel. Chaque objet a le format suivant; l’ID de l’objet est mis en évidence. 


{
      "version": "9bbb9e5d-8115-11e7-8cb4-772d7eb1894d",
      "name": "any-ipv4",
      "description": null,
      "subType": "NETWORK",
      "value": "0.0.0.0/0",
      "isSystemDefined": true,
      "id": "9bbbc56e-8115-11e7-8cb4-01865c95f930",
      "type": "networkobject",
      "links": {
        "self": "https://ftd.example.com/api/fdm/dernière version/object/networks/
9bbbc56e-8115-11e7-8cb4-01865c95f930"
      }

Remarque

Dans certains cas, l’objet {objId} se produit au niveau supérieur d’une hiérarchie. Dans ces cas, vous pouvez parfois saisir n’importe quelle valeur pour l’identifiant de l’objet et obtenir les mêmes résultats. Dans les autres cas, examinez la documentation du modèle d’objet pour obtenir des informations sur les types d’objets valides; l’identifiant est de l’un des types valides. Il s’agit toujours d’appels GET. Par exemple, GET /operational/systeminfo/{objId} et GET /operational/featureinfo/{objId}.

Consulter le catalogue d’erreurs et évaluer les messages d’erreur

Puisque le système est un API REST, il renvoie des codes d’erreur HTTP standard, tels que 404 si vous utilisez la méthode GET pour un objet qui n’existe pas.

En outre, le système comprend un certain nombre de messages d’erreur qui expliquent les erreurs de manière plus précise. Si votre appel d’API génère une erreur, le corps de la réponse peut inclure ces messages plus précis.

Par exemple, si vous essayez d’utiliser la méthode POST /object/networks sur l’objet réseau suivant, vous obtiendrez une erreur. Dans ce cas, vous essayez de préciser un réseau, mais vous avez oublié d’inclure un masque réseau (c’est-à-dire que la valeur doit être 10.10.10.0/24 ou 10.10.10.0/255.255.255.0) : 


{
  "name": "test-network",
  "subType": "NETWORK",
  "value": "10.10.10.0",
  "type": "networkobject"
}

Le résultat serait un code réponse HTTP 422 et un corps de réponse qui comprend un message d’erreur spécifique :


{
  "error": {
    "severity": "ERROR",
    "key": "Validation",
    "messages": [
      {
        "description": "The type Network requires a netmask. To specify a single host, either use the type Host, or use {0}/255.255.255.255.",
        "code": "networkWithoutNetmask",
        "location": "value"
      }
    ]
  }
}

La procédure suivante explique comment consulter la liste des messages d’erreur possibles qui peuvent être renvoyés dans un corps de réponse.

Procédure

Étape 1

Dans le gestionnaire d'appareil, cliquez sur le bouton des autres options (bouton plus d'options.) et choisissez API Explorer (Explorateur d’interface de protocole d’application).

Étape 2

Cliquez sur Error Catalog (Catalogue d’erreurs) dans la table des matières.

Les messages comprennent les éléments suivants.

  • Category (Catégorie) : le type général de message. Cette valeur apparaît dans l’attribut key (clé) du corps de la réponse d’erreur. Les catégories comprennent Validation (Validation), General (Général) et Deployment (Déploiement).

  • Code (Code) : une chaîne unique qui identifie le message d’erreur. Cette valeur apparaît dans l’attribut code (code) du corps de la réponse d’erreur. Vous pouvez utiliser la fonction Find On Page (Rechercher sur la page) du navigateur pour localiser des messages dans le catalogue avec cette valeur.

  • Message (Message) : le message précis qui explique l’erreur. Cette valeur apparaît dans l’attribut description (description) du corps de la réponse d’erreur. Les variables dans le message sont indiquées comme {0}, {1}, etc.