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

exé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
     }
    ]
  }
]

Vous pouvez également préciser que vous souhaitez une réponse au format JSON en le précisant dans l'entête "Accept" de la requête HTTP plutôt que dans la queryString :

  Accept: application/json

Gestion des erreurs

Il existe deux types d'erreurs, les standardisées, et les erreurs de transport.

Dans les deux cas les erreurs sont propagées par le système de code d'état de la requête (les erreurs sont propagées par le système de code d'erreur traditionnel du HTTP) :

le code d'erreur 200 signifie que la fonction s'est éxécutée correctement,
le code 301 et 302 désignent que la fonction a été déplacée,
le code 404 désigne une fonction qui n'existe pas ou plus,
les codes 401 et 403 désignent un manque de droits pour l'éxécution,
et enfin le code 500 désigne une erreur standardisée, décrite ci-dessous.

Tous les autres codes d'erreurs HTTP sont dépendantes soit d'une erreur dans la formulation de la requête HTTP (code 4xx), soit d'une erreur ponctuelle non liée à la fonction (5xx).

Lors d'une erreur 500, vous pouvez récupérer une erreur standardisée qui retrace l'exception et le problème :

GET /core/api/ACL.TraitmentCancel

<PHCAPIError>
  <Error>0</Error>
  <StackTrace>
   à WebServiceCore.API.HttpComponentAPIManager.<>c__DisplayClass28_3.<__BuildResources>b__0(HttpResponse lnk) dans C:\Work\Polaris\dev\sources\WebServiceCore\WebServiceCore\API\HttpComponentAPIManager.cs:ligne 958
  </StackTrace>
  <Message>paramètre 'traitmentName' manquant</Message>
</PHCAPIError>

Gestion de l'identification et des droits d'accès

L'identification est propagée par l'ouverture et la transmission d'un cookie qui contient un jeton de session.

Afin de pouvoir utiliser correctement l'API, vous devez :

appeler la fonction ACL.SSL pour vous voir rediriger sur un port sécurisé si ce n'est pas le cas ; à partir de ce point, toute la communication est protégée ;
toujours propager les cookies de session reçus avec le client HTTP que vous utilisez pour forger et envoyer vos requêtes,
ouvrir une session sur le système en utilisant la fonction de connexion ACL.Login au début de l'échange,
fermer votre session en utilisant la fonction de connexion ACL.Logout à la fin de votre échange.

Le jeton de session fourni est valable au moins 20 minutes entre chaque appel de fonctions.

Liste des fonctions accessibles

La liste des fonctions accessibles est disponible ici : pages relatives au Webservice.

Menu de navigation