Protocole utilisé par les Web Services

View the English version

Le protocole utilisé par les Web Services Timesquare est AtomPub (RFC 5023). C'est un protocole de niveau application qui permet de publier et de modifier des ressources dans leur représentation Atom en utilisant HTTP (RFC 2616).

Les ressources sont groupées dans des collections où une collection contient habituellement des ressources du même type.

Les collections

Il y a deux opérations qui peuvent être faites sur une collection : la récupération du contenu de la collection et l'ajout d'une nouvelle ressource.

La récupération d'une collection (HTTP GET)

La récupération d'une collection se fait par une requête HTTP GET sur l'URI de la collection. Sa représentation va être un document Atom de type feed. Le résultat de la requête peut être influencé par la présence de certains paramètres HTTP dans la requête. Il y a un nombre de paramètres standard qui peuvent être utilisés sur toutes les collections.

Elément	Description
max-results	Le nombre maximum de ressources (entries) qui sont présentes dans la réponse. Avec start-index cela permet la pagination de la collection. Par défaut (s'il n'est pas spécifié) il est à 25.
start-index	L'index dans la collection entière de la première ressource présente dans la réponse, l'index de la première ressource étant 1, qui est aussi la valeur par défaut du paramètre.

En plus, chaque collection peut avoir d'autres paramètres, spécifiques, qui sont décrits avec la collection.

La création d'une ressource (HTTP POST)

Pour créer une ressource il faut envoyer une requête HTTP POST à l'URI de la collection avec la représentation Atom de type entry de la nouvelle ressource. Le serveur répond avec le code 201 CREATED et renvoie l'entry de la ressource créée. Cette entry peut être légèrement différente de celle renvoyée par le client : le serveur est libre de changer ou de supprimer certains éléments, notamment l'élément atomId ne va pas être pris en compte, c'est le serveur qui le génère. Dans l'entête HTTP Location de la réponse il va y avoir l'URI de la ressource créée, qui va être répétée dans l'entête Content-Location si l'entry renvoyée dans la réponse est la représentation complète de la ressource (ce qui est le cas, par défaut). Le client peut alors comparer la représentation reçue avec celle qu'il a envoyée pour se rendre compte des éventuelles modifications que le serveur a pu apporter.

Si la ressource ne peut pas être créée (à cause d'un document entry invalide renvoyé par le client, d'une erreur interne du serveur, etc.) ceci va être signalé par le code réponse HTTP.

Les ressources

La récupération d'une ressource (HTTP GET)

La récupération d'une ressource se fait par une requête HTTP GET sur son URI. Sa représentation va être un document Atom de type entry. L'URI de la ressource peut être retrouvé dans l'élément <atom:link rel="self" href="..."/> de l'entry.

La modification d'une ressource (HTTP PUT)

Pour modifier une ressource il faut faire une requête HTTP PUT sur l'URI donné par <atom:link rel="edit" href="..."/> avec sa nouvelle représentation (sous forme d'un document Atom entry) comme contenu de la requête. Cette représentation doit être complète, elle doit inclure tous les éléments, même ceux qui ne changent pas.

La suppression d'une ressource (HTTP DELETE)

Pour supprimer une ressource il faut faire une requête HTTP DELETE sur l'URI donnée par son link edit. Si la suppression a été faite le serveur va répondre avec le code 204 No Content.

Codes réponse HTTP

Le code retourné dans la réponse d'une requête HTTP est utilisé pour signaler le résultat, notamment s'il y a eu une erreur ou pas. Dans le cas d'une erreur, la réponse va contenir un message lisible par l'utilisateur qui détaille la cause de l'erreur.

Les codes réponse les plus communs sont (liste non-exhaustive).

Elément	Description
200 OK	Pas d'erreur. C'est le code qui est renvoyé pour toute requête qui a été exécuté avec succès, sauf cas particuliers (comme la méthode POST qui renvoie 201).
201 Created	Une ressource a été créée. C'est la réponse normale d'une requête POST pour créer une ressource.
400 Bad request	Requête invalide : l'URI, un de ses paramètres, un entête ou le contenu (le document Atom) est invalide. Ce code retour concerne également les erreurs fonctionnelles.
401 Unauthorized	Requête non-autorisée. La requête a été faite sur une ressource protégée mais le client n'a fourni aucune information d'authentification ou ces infos ne sont pas correctes.
403 Forbidden	La requête est valide mais le serveur refuse de la traiter. La raison du refus est donnée dans le contenu de la réponse.
404 Not Found	Ressource inexistante.
500 Internal Server Error	La requête est valide mais le serveur ne peut pas la traiter à cause d'une défaillance interne.

Les messages d'erreur fonctionnels sont disponibles directement depuis le détail de chaque Web Service. Les messages sont exclusivement en français.

D'autres codes peuvent apparaître comme réponse et ils doivent être traités comme spécifié dans le RFC du protocole HTTP.

Si le code est du type 4** (erreur client) ou 5** (erreur serveur) le serveur doit fournir une description de la cause de l'erreur lisible par l'utilisateur.

Cette réponse est une page HTML selon le prototype suivant :

<html>
<head>
<title>Courte description</title>
</head>
<body bgcolor="#FFFFFF" text="#000000">
<h1>Courte description</h1>
<h2>Code ***</h2>
<p>Description détaillée</p>
</body>
</html>

La description courte est la même que celle qui apparaît après le code réponse dans l'entête et * est le code. La description détaillée est optionnelle. Elle peut fournir plus de précisions comme par exemple la ligne et la colonne où il y a une erreur dans un document XML invalide.

Document de service Atom

Le document de service Atom permet à un client de découvrir de façon dynamique les collections de ressources mises à disposition par le serveur. Ce document énumère les collections de base (qui ne sont pas des sous-ressources) regroupées dans des workspaces. Il peut être récupéré par une requête HTTP GET sur l'URI de base des Web Services. Cet URI est l'URI de base de l'application auquel on rajoute /api/feed, par exemple si l'URI de l'application est http://serveur/Timesquare, l'URI de base des services est http://serveur/Timesquare/api/feed.

Compression du contenu avec gzip

Pour limiter le volume de données transférées il est possible d'utiliser gzip pour compresser le contenu des requêtes et des réponses HTTP.

Pour que le serveur compresse sa réponse il suffit d'ajouter Accept-Encoding: gzip dans l'entête de la requête.

Si le client envoie une requête avec son contenu compressé il faut qu'il rajoute Content-Encoding: gzip dans l'entête.