Les services web de type REST

Fiche ressource Article, événement, site web...
  • Création ou MAJ importante : 22/10/10
  • Correction mineure : 01/12/11
Mots-clés

Les services web de type REST

  • Type de ressource : résumé
  • Date de publication du document ou de l'événement : Oct 2010
  • Auteur(s) ou responsable(s) : P. Gambarotto (INPT/Enseeiht)

REST (REpresentational State Transfer) est un style d’architecture pour concevoir un service web, utilisant au maximum les possibilités de HTTP. Ses principales caractéristiques sont les suivantes :

  • application client/serveur : le transport sur le réseau est assuré par HTTP (essence même d’un web service)
  • interface uniforme : tout élément offert à la manipulation par l’application est nommé ressource et est identifié de manière unique par les Identifiants de Ressource Uniforme (URI ci-après) suivant le schéma :

    http_URL = “http:” “//” host [”:” port]

    Deux types de schéma d’URI sont distingués :

    • URI member qui désigne une seule ressource.
    • URI collection qui désigne une liste de ressources de même type.
  • la sémantique des messages du client au serveur est celle de HTTP :

    • GET URI : récupérer la représentation d’une ressource (URI member), ou d’une liste de ressources (URI collection)
    • POST URI (collection) : rajouter une ressource à une liste de ressources existantes, donc création de ressource.
    • PUT URI (member) : modifier une ressource existante ou créer une nouvelle ressource.
    • DELETE URI : destruction d’une (URI member) ou plusieurs (URI collection) ressources.
  • les réponses du serveur aux clients utilisent également les messages HTTP, en particulier les codes d’erreur suivants :

    • 200 Ok
    • 404 Ressource non trouvée sur le serveur
  • représentation des ressources : le format avec lequel une ressource est représentée est obtenu par négociation grâce aux entêtes HTTP. Le client indique ce qu’il souhaite comme format de représentation avec l’entête ”Accept”, le client et le serveur utilisent l’entête ”Content-type” pour décrire le format de représentation de la ressource incluse dans le message. Les formats les plus fréquemment rencontrés sont XML et JSON.

API REST : exemple détaillé

Pour illustrer les principes de création d'une API s'appuyant sur les principes REST, je vais décrire une gestion d'utilisateurs très générale, telle qu'on la retrouve souvent dès qu'une application a besoin de gérer une authentification de ses utilisateurs. Les utilisateurs sont identifiés en tant que ressources par un schéma d'URI du type :

http://server/user/id

où id est une clef permettant d'identifier de manière unique la ressource, par exemple le login pour un utilisateur. L'ensemble des utilisateurs est référencé par le schéma d'URI

http://server/users

(notez bien le pluriel). Les différentes actions possibles sur ces deux types de ressource sont :

GET http: // server / users
Récupère la liste de tous les utilisateurs (Réponse : 200 OK)
POST http: // server / user / id_user
Création d'un nouvel utilisateur (Réponse : 201 Created)
GET http: // server / user / id_user
Récupère la représentation de l'utilisateur identifié par id_user (Réponse : 200 OK ou 404 resource not found)
PUT http: // server / user / id_user
Modifie un utilisateur (Réponse : 200 OK ou 404 resource not found)
DELETE http: // server / user / id_user
Efface un utilisateur (Réponse : 200 OK ou 404 resource not found)

Les deux premiers schémas de requêtes adressent la collection entière des utilisateurs, tandis que les suivants visent un membre particulier de la collection. Ce sont deux types de ressources différents, c'est donc normal que le schéma d'URI soit spécifique à chacun.

Dans une API REST on retrouve presque systématiquement cette dualité collection/membre. Notez que http: // server / user (au singulier) aurait pu être l'URI identifiant la collection. C'est à la partie serveur de réaliser l'analyse des requêtes pour déterminer quelles sont les ressources visées par une requête particulière.

Représentation des ressources

JSON est utilisé pour représenter les deux types de ressources, utilisateur et liste d'utilisateurs.

  • Utilisateur :
{user:{login: id_user, password: secret }}
  • Liste :
[{user:{login: id1, password: secret1}}, {user:{login:id2, password:secret2}}]

Un utilisateur est donc ici représenté par un login et un password.

Bibliographie

  1. Fielding, Roy Thomas, Architectural Styles and the Design of Network-based Software Architectures, 2000
  2. Fielding and al, Hypertext Transfer Protocol -- HTTP/1.1, 1999
  3. J. Gregorio, B. de hOra, The Atom Publishing Protocol, 2007
  4. D. Crockford, The application/json Media Type for JavaScript Object Notation (JSON), 2006
  5. Leonard Richardson, Sam Ruby, RESTful Web Services, 2007