NF13075 — Interface de programmation applicative par Webservice (API)

Voir la carte de la fonctionnalité : Autres outils

L'API par Webservice vous permet de piloter ou d'interroger votre solution de gestion depuis un programme externe : c'est par son intermédiaire que le prestataire tiers choisi va mettre en place l'interconnexion à votre backoffice. Cette documentation lui est donc principalement destinée.

En effet, une interface de programmation applicative (désignée par le terme API pour Application Programming Interface) est un ensemble normalisé de classes, de méthodes ou de fonctions qui sert de façade par laquelle un logiciel offre des services à d'autres logiciels.

Dans le cas de Polaris, elle est offerte par un service web, accessible sur chaque service de réplication.

Choix techniques

Pour commencer

Notre API est bâtie sur l'exploitation d'un webservice, donc sur un échange HTTP pour lequel nous respectons le standard 1.1. Elle est compatible notamment avec les échanges sécurisés (SSL).

Pour échanger avec notre webservice, il faut donc le faire à travers un client HTTP traditionnel en manipulant des URI.

L'API est ouverte et accessible sur l'URL suivante : https://xx.xx.xx.xx:3443/core/api/.

Méthodes d'accès à l'API

Toutes les fonctions exposées par l'API sont assimilées à des ressources HTTP traditionnelle, le nom de la fonction est donc le nom de la ressource ;

Vous pouvez déclencher la fonction en appelant la ressource soit :

• en méthode HTTP GET, les paramètres sont transmis en queryString ;
• en méthode HTTP POST, chaque paramètre est transmis soit dans la queryString, soit dans le corps de la requête, au format application/x-www-form-urlencoded.

Notons qu'il ne s'agit ni d'un webservice de type SOAP, ni d'un service de type REST, par conséquent, les méthodes HTTP PUT, DELETE, et HEAD ne sont pas supportées.

Par exemple, la requête suivante :

GET /core/api/ACL.Login?user=test&password=testmdp

éxécute la fonction ACL.Login, avec pour paramètres :

• user avec la valeur test,
• password avec la valeur testmdp.

Important !

Les valeurs étant passées dans la queryString, il faut nécessairement qu'elles soient encodées au format URL, notamment si elle contiennent le séparateur de champs (&) : ainsi, la valeur «test & autre» devient «test%20%26%20autre»

Gestion des réponses

A moins que le contraire ne soit clairement explicité dans leur documentation, comme par exemple l'API qui fourni les photos des produits, par défaut toutes les fonctions peuvent fournir leur réponses au format JSON ou XML, au choix lors de l'interrogation. C'est également valable pour les erreurs standardisées.

Exemple :

GET /core/api/Health.ProcessList?output=xml

<ArrayOfProcessInfo>
  <ProcessInfo>
    <Id>15</Id>
    <Name>ips</Name>
    <OwnerType>0</OwnerType>
    <Owner/>
    <OwnerName/>
    <Tasks>
      <ProcessInfoTask>
        <Date>2017-09-29T13:44:58.3608012Z</Date>
        <TaskName>Attente</TaskName>
      </ProcessInfoTask>
    </Tasks>
  </ProcessInfo>
</ArrayOfProcessInfo>

GET /core/api/Health.ProcessList?output=json

[
  {
   "Id":15,
   "Name":"ips",
   "OwnerType":0,
   "Owner":"",
   "OwnerName":"",
   "RemoteEndPoint":null,
   "Tasks":[
     {
      "Date":"\/Date(1506692818379)\/",
      "TaskName":"Attente",
      "Step":null
     }
    ]
  }
]