Manuels d'intégration › Manuel de référence de l'API de service Web › Syntaxe générique d'API

Syntaxe générique d'API

Pour initialiser une requête API pour un objet, utilisez une commande présentant le format suivant :

GET "http://IP-WS/api/v1/objet/méthode?arg1=<valeur>&arg2=<valeur>&vdc=<grille>"

Où :: IP-WS est l'adresse IP utilisée pour accéder à l'application WS_API ;
objet est un objet API (par exemple, app, class, etc.) ;
méthode est l'action à effectuer pour l'objet (par exemple, start, stop, etc.) ;
arg1, arg2 sont les arguments à transmettre à la méthode ;
vdc est le nom du contrôleur de grille
Commentaires

Syntaxe d'option avec valeur : une option avec valeur se présente généralement au format suivant :
```
<property_name>=<value>
```
La valeur doit être codée au format URI (Uniform Resource Identifier) sous forme de pourcentage, d'après les règles spécifiques au chemin d'accès de l'URI. Remplacez les caractères réservés du champ de chemin d'accès de l'URI (par exemple, signe de pourcentage, espace et tabulation, signe égal, virgule, barre oblique, point d'interrogation, guillemets simples et doubles) par leur version codée sous forme de pourcentage %HH, où HH est la représentation ASCII hexadécimale du caractère concerné.

Remarque : Pour plus de détails sur le codage d'URI, consultez la norme RFC 3986.

Syntaxe d'indicateur d'option : bien que l'interface de ligne de commande utilise un trait d'union double ou le tiret cadratin (—) comme préfixe pour désigner un indicateur d'option (en général, une option sans valeur), l'API de services Web continue à employer l'esperluette (&). Par conséquent, dès lors que l'interface de ligne de commande utilise --option, les services Web emploient &option à la place. Par exemple, si l'interface de ligne de commande utilise --debug, l'API de services Web emploie &debug à la place.
Bien que les descriptions des demandes d'API concernant un objet comportent tous les paramètres obligatoires, elles n'incluent que quelques paramètres facultatifs. Les paramètres facultatifs non inclus dans ce manuel sont décrits dans le Manuel de référence du shell de ligne de commande.

Exemple :

Pour obtenir les méthodes de l'objet app :
curl http://192.168.123.200/api/v1/obj/info?obj=app&vdc=mygrid

Exemple de sortie :

{
   "method" : [
      {
         "name" : "config"
      },
      {
         "name" : "copy"
      },
      {
         "name" : "create"
      },
      {
         "name" : "destroy"
      },
      .
      .
      .
   ]
}

Formats de sortie

Les formats de sortie acceptables sont XML et JSON. Vous pouvez les spécifier dans la requête API.

Exemple :

Pour obtenir les méthodes de l'objet app au format XML :

curl http://192.168.123.200/api/v1/obj/info?obj=app&vdc=mygrid -H "Accept: application/xml"

Pour obtenir les méthodes de l'objet app au format JSON :

curl http://192.168.123.200/api/v1/obj/info?obj=app&vdc=mygrid -H "Accept: application/json"

Remarque : Toute la sortie au format JSON est codée au format UTF8. Utilisez un décodeur UTF8 pour la décoder. Exemple de script PHP simple pour décoder une sortie JSON codée en UTF8 :

<? 
$json = '{"a": "\u00e3\u0081\u0082" }'; 
$j = json_decode($json); 
echo utf8_decode($j->{'a'}); 
?>

Ce chapitre traite des sujets suivants :

Types d'argument communs

Vous pouvez utiliser le type d'argument générique ci-dessous qui est commun à de nombreuses commandes. Lorsqu'un type d'argument spécifique est référencé à partir d'une description de commande particulière, utilisez les informations détaillées suivantes pour le type considéré :

<principal>

<principal> représente une personne, c'est-à-dire un individu ou un groupe, ayant une portée donnée, locale ou globale. Spécifiez un principal en utilisant une des syntaxes possibles suivantes :

<name>: Utilisateur ou groupe local.
/<name>: Utilisateur ou groupe global.
<scope>:<type>:<name>: Nom complet de principal où <scope> a la valeur global ou local, <type> correspond à group ou user, et <name> est le nom du groupe ou de l'utilisateur.

Remarque : Un principal doit être codé au format URL. Par exemple, local:user:api@3tera.com doit être passé sous la forme local%3Auser%3Aapi%403tera.com