HubSessions dispose d'une API de type XML/HTTP, permettant tant de consulter que d'injecter des données.

Principes de l'API

Format des échanges

Un logiciel tiers peut interagir avec HubSessions au moyen de requêtes HTTP de type GET, POST, PUT ou DELETE, qui retournent (et parfois envoient) des données au format XML encodées en UTF-8. Ces réponses peuvent aller du simple accusé de réception (succès ou erreur suite à une opération d'écriture, par exemple) à une structure de données complexe définissant, par exemple, un objet exposé par HubSessions. Les requêtes de type GET peuvent disposer de paramètres à encoder directement dans l'URL, tandis que les requêtes de type POST, PUT et DELETE permettent d'envoiyer une charge utile de type XML, dont le format varie de service en service.

Au sein des réponses, certains champs pourront contenir des URLs vers d’autres requêtes, permettant à l'appelant de compléter, via des requêtes GET complémentaires, l’information réceptionnée par la première requête.

Authentification

Toute requête sera effectuée via une authentification de type « Basic HTTP Authentication », via un login et un mot de passe.

Fichiers binaires

Tout échange de fichiers binaires, que ce soit en injection par un logiciel tiers vers HubSessions ou en consultation depuis HubSessions, se fait au sein même des charges utiles XML, à l'intérieur desquelles des tags contiendront tout ou partie des fichiers binaires, encodés en Base64.

Partons d'un exemple, qui, afin que vous ne vous épuisiez pas à scroller indéfiniment sur cette page, a tronqué les parties encodées en Base64.

<file type="file" mimeType="image/png" name="LibreOffice.png">
  <part type="base64" number="1">iVBORw0KGgoAAAANSUhEUgAAA...</part>
  <part type="base64" number="2">rsnY99YHNva8QBcCTUSEcYClG8RKJv2XU...</part>
</file>

Un fichier binaire, contenu et métadonnées incluses, est quasi toujours transbahuté dans un tag nommé file. Ce tag doit contenir les métadonnées suivantes: un type (valant "file", comme sur l'exemple), le type MIME du fichier et un nom polissé (attribut name) pouvant apparaître aux yeux prudes de l'utilisateur final.

Ensuite, un ou plusieurs sous-tags nommés part doivent charrier le contenu du fichier. Chaque partie doit mentionner son type valant "base64" et son numéro d'ordre (attribut number, dont la première manifestation doit être 1 et non 0) parmi la séquence des parties du même fichier. Quant au contenu du tag, vous aurez compris qu'il s'agit de l'encodage en Base64 de la partie du fichier.

Vous pourriez penser: mais pourquoi découper ces satanés fichiers binaires en morceaux? Peut-être le développeur de cette API fut-il influencé par quelques films visionnés lors de sa plus tendre enfance, comme Massacre à la Tronçonneuse. Ou peut-être a-t-il constaté que décoder des bouts courts de chaînes encodées en Base64 et concaténer les morceaux était plus performant qu'un décodage d'une chaîne unique plus longue. Quoi qu'il en soit, HubSessions découpe systématiquement ses fichiers binaires en morceaux de 50 000 octets (ce nombre étant susceptible de changer à tout moment sans préavis): il est vivement conseillé aux logiciels tiers appelants de faire de même. D'avance merci. Les plus perspicaces d'entre vous auront constaté que les chaînes de codage Base64, lorsque lues à haute voix par un humain ayant calé sa glotte, produisent la bande-son du film mentionné plus haut.

Format de retour standardisé

La plupart des services injectant des données dans HubSessions retourne une réponse de succès ou d'erreur qui suit un format standardisé, dont voici une illustration.

<?xml version="1.0" encoding="utf-8" ?>
<Response type="object">
 <code type="int">0</code>
 <text>Success</text>
 <data/>
</Response>

Le tag principal d'une réponse standardisée sera toujours Response.

Ensuite, un code applicatif est fourni (sous-tag code). Il vaut 0 si l’appel au service n’a produit aucune erreur. Ce code applicatif, comme son nom l’indique, est un code lié à l’application et à sa fonctionnalité : il ne représente pas un code de retour HTTP.

Voici quelques considérations importantes.

• Si vous essayez d’accéder à un service alors que vous fournissez une combinaison login/mot de passe erronée, le service vous retournera un code HTTP de retour 403.
• Si vous appelez un service et qu’une erreur interne, non gérée, se produit dans HubSessions, vous recevrez un code HTTP de retour 500. Notez que ce sera le cas si, par exemple, vous omettez de typer un tag requérant un typage par HubSessions, telle une date, par exemple, qui ne disposerait pas de l’attribute type="DateTime".
• Si vous essayez d’appeler un service dont le nom est erroné, vous récupérerez un code de retour HTTP 404.
• Dans la plupart des autres cas, vous recevrez un code de retour 200. Alors que, dans les exemples précédents, il est en général inutile d’accéder au corps de la requête (sauf pour récupérer le détail de l’erreur sous la forme d’un message textuel en cas d’erreur 500), dans ce cas-ci, c’est opportun, et, au sein de ce corps, formaté en XML comme illustré ci-dessus, vous trouverez donc un code indiquant le succès ou l’échec de l’appel, en termes applicatifs.

Au-delà du code applicatif, un texte court (tag text) donnera plus de détails au sujet du succès ou de l’erreur éventuelle.

Si le service doit retourner des données spécifiques, celles-ci seront disponibles sous le tag data.

La page de détail d'un service vous précisera si le service en question fait usage de ce format de retour ou non, et si oui, quel est l'éventuel format détaillé du sous-tag data.

Le tableau suivant liste les types d’erreurs. Ils sont communs à l’ensemble des services les utilisant, car ils s’appliquent à la notion abstraite d’objet, dont les différents concepts d'HubSessions (point, séance, annexe, dossier, etc) sont des manifestations.

Services

Le tableau suivant liste les services disponibles. Un clic sur le nom d'un service vous emmènera sur sa page détaillée.

L’URL de base pour appeler chaque service sera notée <siteUrl>. L'URL complète d'un service se détermine en ajoutant le nom du service à cette URL de base. Par exemple le service "create/item" a l'URL complète <siteUrl>/create/item.