REST : Comment bien concevoir les ressources collections

Comme nous l’avons indiqué dans le post sur les ressources en REST : “Une ressource est une correspondance conceptuelle à un ensemble d’entités, et non l’entité correspondante à un moment donné”. Certaines ressources contiennent un grand nombre de ressources “membres”, ces premières sont souvent référées comme “ressources collections”. Les clients qui consomment ces ressources collections sont souvent besoin d’un moyen pour récupérer une partie de la collection (paginer). Dans cet article, nous allons voir les bonnes pratiques pour représenter une collection paginée.

L’une des contraintes essentielles du protocole REST est le fait qu’il soit sans état (stateless).  Quand un serveur retourne un sous ensemble de membres dans une représentation d’un ressource collection, le serveur doit donner des liens pour permettre au client de paginer sur le reste des membres.

Supposons que nous voulons une ressource “articles” qui nous permet de récupérer la liste des articles disponibles. cette ressource collection retourne des ressources membres. Nous requetons alors la ressource comme suit :

#requete
GET /articles?start=10 HTTP/1.1 
Host: www.exemple.org

Cette requête récupère une collection en commençant par le dixième article disponible (d’ou le start=10), la reponse peut être la suivante:

# réponse 
# Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8 Content-Language: en
{
  "total":"35",
  "links" {
    "self":"http://www.exemple.org/articles?start=10",
    "prev":"http://www.exemple.org/articles",
    "next":"http://www.exemple.org/articles?start=20"
   },
   "articles":[
     {
        "links": {
           "self":"http://www.lapresse.ca/actualites/national/201401/02/01-4725145-hydro-
quebec-appelle-a-reduire-la-consommation-delectricite.php"
         },
        "title":"Hydro-Québec appelle à réduire la consommation d'électricité",
        "body":"Hydro-Québec demande à ses abonnés d'économiser l'électricité, alors que 
des records historiques de froid sont battus partout au Québec. La société d'État éteindra 
même l'enseigne 
qui orne son siège social montréalais afin de montrer l'exemple.",
         ...
      },
{
        "links": {
           "self":"http://www.lapresse.ca/actualites/national/201312/29/01-4724650-fin-du-
deneigement-par-temps-glacial.php"
         },
        "title":"Fin du déneigement par temps glacial",
        "body":"L'hiver s'installe et ne prend pas de vacances pour les Fêtes. Le mercure
 pourrait chatouiller les -30 °C vers le milieu de la semaine, alors que le déneigement 
des rues de Montréal <br>est presque terminé... sept jours après la dernière vraie tempête.",
         ...
      },
  ]
}

Dans la représentation ci-dessus, nous remarquons qu’il y’a quelques informations permettant la navigation :

• la taille de la collection : permet au client d’implémenter la logique de pagination et de savoir quand s’arrêter.
• le lien “self” : le lien du sous ensemble courant de la collection
• le lien “prev” : le lien du sous ensemble précédent, s’il y’a lieu
• le lien “next” : le lien du sous ensemble suivant, s’il y’a lieu

de cette façon, Indépendamment du serveur, les clients sont capables de naviguer dans la ressource au complet en se basant uniquement sur l’information retournée. D’ailleurs, du point de vue de HTTP, Chaque “page” récupérée est une ressource différente, puisqu’elle est définie par une URI distincte.