Posts Tagged ‘web2.0’

Cet article de Joe Gregorio est paru, en anglais, sur XML.com le 1er décembre 2004, sous le titre : How to Create a REST Protocol

Note : dans cet article inaugural de la nouvelle rubrique de Joe Gregorio, le Web Restful, il explique comment uiliser une architecture REST pour créer un protocole d’application avec les propriétés d’une application web. Les futurs articles offriront des applications et analyses additionnelles sur REST. – L ‘Editeur en chef

Si vous suivez les services web, vous devez avoir entendu parler de REST. REST est un style d’architecture qui peut être utilisé comme base pour la construction de service web. Récemment, il a été tenté de créer de tels services avec un succès mitigé. Cet article souligne une série d’étapes que vous pouvez suivre pour créer votre protocole – des conseils qui vont vous aider à bénéficier de ce que REST a à offrir, tout en évitant les pièges habituels.

Qu’est-ce que REST ?

Au fait, qu’est-ce que REST ? C’est un style d’architecture. Un style d’architecture est des contraintes nommées et regroupées.

Une architecture logicielle est définie par une configuration d’éléments architecturaux – composants, connecteurs, et données – contraints dans leurs relations pour mettre en place un ensemble voulu de propriétés architecturales. [Roy Fielding]

Pourquoi utiliser REST ?

Les pourquois sont couverts sur le Wiki REST. Il possède des avantages, de la scalabilité à la simplification de l’implémentation, en passant par l’augmentation des possibilités de votre service à être réutilisé. Jon Udell a écrit deux bons articles : The Beauty of REST etTangled in Threads: The power of the URL-line, qui couvrent tous les bénéfices d’un système ‘modulaire’.

Voyez le comme ceci : si vous utilisez une infrastructure web pour répartir vos données, ne devrait-elle pas suivre des bonnes pratiques qui vont vous aider à envoyer vos données plus souplement à travers le système ? C’est mieux de suivre le flux que d’essayer de nager à la surface.

Comment créer un interface RESTful

Maintenant entrons dans le vif du sujet. Au lieu de voir cela d’une vue architecturale, mon approche sera depuis des recettes, une série d’étapes à franchir et de questions auxquelles vous pouvez répondre, ce qui, je l’espère, vous aidera à créer une bonne interface REST.

Pour créer un service REST, vous devrez répondre aux questions suivantes, et vous devez y répondre dans l’ordre :

  1. Quelles sont les URIs ?
  2. Quel est le format ?
  3. Quelles méthodes seront supportées par chaque URI ?
  4. Quel code sera retournée ?

En posant ces questions, je n’ai pas utilisé les noms conventionnels appropriés, au lieu de cela, j’ai utilisé des noms communs pour des choses avec lesquelles la plupart des développeurs sont familiers. Quand nous répondrons à chacune des questions, j’introduirais la nomenclature correcte.

Question 1 : Quelles sont les URIs ?

La nomenclature correcte serait « Quelles sont les ressources ? » Les choses identifiées par URIs sont des « ressources ». C’est la terminologie que Roy Fielding utilise dans sa thèse, et c’est la même terminologie qui est utilisée dans Architecture of the World Wide Web, First Edition. Les ressources sont identifiées par des URIs.

Vous pouvez créer un protocol RPC, ou pire, si vous avez une seule URI à travers laquelle tout passe. Il ya des années de cela, un des premiers services intranet que j’ai monté était une interface web pour un système ECO (Engineering Change Order). Chaque fois qu’une partie était modifiée, un ECO (ordre de modification) était créé et avait à naviguer à travers ce système. J’ai créé un seul script qui gérait le système entier, un seul script qui prenait tous ses paramètres par POST. Cela signifiait qu’il n’y avait pas moyen de marquer la page dans le système; chaque page avait la même URI : /cgi-bin/eco.cgi. Les employés voulaient marquer la page de certains ECOs ou envoyer des liens par email, mais ils ne pouvaient pas parce que la barre d’adresse ne changeait jamais. Cétait toujours la même /cgi-bin/eco.cgi, immobile, comme le 12:00 clignotant d’un réveil déprogrammé. Les employés ne connaissaient par REST, mais ce qu’ils savaient implicitement c’est que chaque ressource, en ce cas, chaque ECO, devait avoir sa propre URI.

Décomposez votre problème en types de ressources que vous voulez manipuler. La chose à se rappeler est que chaque ressource doit avoir sa propre URI. Essayez de lister toutes les ressources dont vous pouvez avoir besoin à cette étape. Les deux endroits à examiner quand on cherche des ressources potentielles sont les collections et les moteurs de recherche. Une « collection de ressources » peut, en elle-même, être système de ressource complet.

Un moteur de recherche est une autre source de ressources. Vous entrez un critère pour les ressources que vous voulez trouver, et une liste des ressources correspondantes est retournée. Vous pouvez remarquer, donc, que les résultats sont juste une collection de ressources, qui correspond à un critère particulier, et en tant que telle, c’est juste une plus petite version du premier cas de la collection de ressources.

Considérons un exemple très simple de système pour maintenir un annuaire des employés. Pour notre exemple, il contiendra les nom, titre et informations de contact de chaque employé. Dans un tel système, chaque utilisateur doit avoir sa propre URI avec la représentation appropriée. Cette représentation devra contenir les nom, titre et informations de contact pour cet employé.

C’est aussi une collection de ressources, qui en elle même est une autre ressource. L’ensemble de tout les employés est une ressource dans notre système. Nous avons donc identifé deux sortes de ressources dans ce petit système, il y aura donc deux types d’URIs :

  1. Employés (une URI par employé)

  2. Tous les employés

Après avoir identifié les ressources par leurs URIs, il est temps de passer à la question suivante.

Question 2 : Quel est le format ?

La terminologie correcte est « représentation ». Vous ne pouvez pas vraiment atteindre et toucher les ressources derrière les URIs que vous avez identifiées à l’étape 1. Ce que vous pouvez faire est échanger des représentations de ces ressources. Quand je fais un GET sur une ressource « employé », j’ai besoin d’un retour qui me fournit les informations sur cet employé. Actuellement, HTML, XML, images, sons et vidéos sont des formats potentiels qui peuvent être utilisés. Pour l’exemple nous nous restreindrons au XML : c’est un format populaire, beaucoup d’outils sont disponibles pour le manipuler, et quand vous dites « services web », on s’attend à ce que vous parliez surtout d’échange de documents XML. Et, oui, c’est publié sur XML.com !

Pour chacune des ressources que vous avez listées à l’étape 1, vous devez décider quelle représentation il y aura. Si possible, réutilisez les formats existants s’ils sont adaptés. Cela peut augmenter les chances que votre système puisse être connecté avec d’autres systèmes.

Dans notre exemple d’annuaire des employés ci-dessus, nous pourrions avoir les représentations suivantes :

Format de l’employé

Pour la beauté de l’exposé, je vais créer un nouveau format XML pour cette information. «Exposé» — « Un rapport ou un discours rhétorique prévu pour donner l’information approchante ou une explication matériellement complexe » — cela signie simplement que je vais tricher pour que vous appreniez quelque chose.
<employee xmlns='http://example.org/my-example-ns/'>
    <name>Full name goes here.</name>
    <title>Persons title goes here.</title>
    <phone-number>Phone number goes here.</phone-number>
</employee>

Format de la liste des employés

Etant donné que chaque employé a sa propre URI avec tous les détails, notre liste va seulement inclure cette URI.
<employee-list xmlns='http://example.org/my-example-ns/'>
    <employee-ref href="URI of the first employee"/>
         Full name of the first employee goes here.</employee>
    <employee-ref href="URI of employee #2"/>Full name</employee>
    .
    .
    <employee-ref href="URI of employee #N"/>Full name</employee>
</employee-list>

Notez que nous n’avons pas planifié la représentation des ressources jusqu’ici. Pour faire cela, nous devons considérer les méthodes.

Question 3 : Quelle méthode sera supportée par chaque URI ?

Dans la nomenclature correcte, comment les URIs que nous avons définies à l’étape 1 seront déréférencées ?

Les agents peuvent utiliser une URI pour accéder à la ressource référencée ; c’est appelé déréférencé l’URL. L’accès peut prendre plusieurs forrmes, incluant extraire la représentation d’une ressource (par exemple en utilisant HTTP GET ou HEAD), ajouter ou modifier la représentation d’une ressource (par exemple, en utilisant POST ou PUT, ce qui dans quelques cas peut changer l’état réel de la ressource si la représentation soumise est interprétée par des instructions adéquates), et effacer certaines ou toutes les représentations de la ressource (par exemple, en utilisant HTTP DELETE, ce qui dans certains cas peut aboutir à l’effacement de la ressource elle-même) [Architecture of the World Wide Web, First Edition]

Nous allons restreindre le débat de l’accès à une ressource en utilisant une des qatres méthodes de base d’HTTP qui peuvent être appliquées à une URI : GET, POST, PUT et DELETE. HEAD est en fait un GET sans le corps de la réponse, et il y en a aussi d’autres définies dans la RFC 2616 comme OPTIONS. En plus, les spécifications comme WebDAV introduisent encore plus de méthodes. C’est sympa, mais vous devriez être capable d’aller vraiment loin avec les quatres méthodes de base, qui correspondent parfaitement avec CRUD, un acronyme du monde des bases de données, qui signifie Create, Retrieve, Update, and Delete.

Méthode HTTP

Action CRUD

Description
POST CREATE Crée une nouvelle ressource
GET RETRIEVE Donne la représentation d’une ressource
PUT UPDATE Met à jour une ressource
DELETE DELETE Efface une ressource

J’ai hésité à inclure ce tableau. En le présentant, je voulais mettre en évidence le recouvrement des quatre méthodes de base du protocole HTTP. Ce que je ne veux pas, c’est que vous commenciez à penser aux ressources web en tant que tables SQL. Ne faites pas cela.

Soyez certains que vos GETs sont sans effets secondaires. C’est un points noirs, le point sur lequel beaucoup de services ont faux. Les GET doivent être à la fois sûres et idempotent. Par conséquent, tout ce qui n’a pas d’effet secondaire doit utiliser GET.

Si vous souhaitez créer une nouvelle ressource, utilisez POST. Retrouver la représentation d’une ressource ? Utilisez GET. Pour mettre à jour la ressource courante, utilisez PUT. Enfin, pour effacer une ressource utilisez DELETE.

Une fois que vous avez mis au point les URI (étape 1), choisi une représentation (étape 2), et décidé des méthodes (étape 3), vous avez besoin de les faire correspondre. Au minimum, vous aurez besoin de sélectionner une représentation pour la réponse de chaque requête GET et une représentation à placer dans la requête pour PUT et POST. Eventuellement, vous pouvez vouloir fournir la représentation, si quelque chose est retournée d’un POST.

Maintenant retournons à notre liste des coordonnées des employés, et nous pouvons faire correspondre les ressources, les représentations et les méthodes.

ressource
Ressource
Method
Méthode
Representation
Représentation
EmployeeEmployé GET Employee Format
EmployeeEmployé PUT Employee Format
EmployeeEmployé DELETE N/A Non disponible
Tous les employésAll Employees GET Employee List Format
Tous les employésAll Employees POST Employee Format

Question 4 : Quel code doit être retourné ?

Non seulement vous avez besoin de savoir quel type de représentation est retourné, vous aurez également besoin d’énumérer les codes de statut HTTP typiques qui doivent être retournés. Dans une monde parfait, cette étape ne serait pas nécessaire du moment qu’une bonne implémentation retournerait correctement chaque code de statut. En pratique, vous devez lister tous les codes de statut desquels vous attendez un retour. Cela fournira un bon guide pour les développeurs sur les conditions qui doivent être testées.

Nous mettrons à jour le tableau pour notre liste de coordonnées des employés pour inclure les codes de statut attendus.

Ressource Méthode Représentation Code de statut
Employé GET Employee Format 200, 301, 410
Employé PUT Employee Format 200, 301, 400, 410
Employé DELETE Non disponible 200, 204
Tous les employés GET Employee List Format 200, 301
Tous les employés POST Employee Format 201, 400

Signaux d’alerte

Même en suivant ces étapes, vous pouvez encore faire quelques erreurs. Paul Prescod a créé une liste des erreurs courantes avec REST qui vaut la peine d’être passé au crible pendant que vous travaillez sur votre protocole.

Récap

Maintenant récapitulons. Pour construire un bon service REST, vous devez répondre aux questions suivantes :

  1. Que sont les URIs ?
  2. Quel est le format ?
  3. Quelles actions sont possibles pour chaque URI ?
  4. Quels statuts doivent être renvoyés ?

Et c’est tout. Vous ne me croyez pas ? Bien, car ce n’est pas vrai. Il y a beaucoup plus à prendre en compte, comme la compresssion, les etags, le cache, l’extensibilité, l’idiome et les implémentations. Au prochain mois.

Publicités