APIs RESTful et Marketing : l’avènement du REST-like

May 19, 2009 | In: Applications Web

Tout le monde parle de REST :

  • certains veulent essayer de comprendre ce qu’est vraiment REST : j’ai déjà commencé à apporter ma modeste contribution sur le sujet et je suis loin d’avoir dit mon dernier mot sur le sujet ! Je compte dès que possible y consacrer encore quelques posts bien précis…
  • d’autres exposent des APIs qu’ils présentent comme RESTful : Google, Yahoo, Twitter, Facebook, E-Bay, Flickr pour ne citer qu’eux… C’est à eux que je veux consacrer ce post.

En effet, ces acteurs prépondérants de la sphère du Web 2.0 sont de facto des référents dans les technologies qu’ils mettent en avant : s’ils exposent des APIs en les déclarant RESTful, il est bon pour le “commun des mortels” de savoir si tel est vraiment le cas. Les aspects théoriques de REST sont déjà suffisamment difficiles à appréhender, alors si les exemples pratiques mis en avant ne sont pas de bons exemples, comment s’y retrouver ?

Prenons quelques exemples d’API dites RESTful au hasard (le hasard étant ici représenté par les trois premières pages de résultats d’une recherche Google sur l’expression “REST API”).

Exemple n°1 : E-Bay

Je n’ose pas m’aventurer dans les méandres de cette documentation plutôt austère. Cependant on repère rapidement un anti-pattern REST de base : dans les requêtes, le nom du service à invoquer est porté par un paramètre HTTP nommé “callname” et non par la méthode HTTP :

http://open.api.ebay.com/shopping?callname=FindItems&…

En outre, on dispose d’un point d’entrée unique mais la notion de ressource n’apparaît pas vraiment.

Exemple n°2 : Twitter

Dans ce cas, la documentation est bien plus simple et attrayante. Elle repose a priori sur un découpage en ressources (timeline, status, user…) sauf que là encore le nom du service est transmis dans l’URI et non via la méthode HTTP :

http://twitter.com/statuses/destroy/12345.json

Ainsi on envoie une requête POST sur cet URI au lieu d’une requête DELETE sur un URI de la forme suivante :

http://twitter.com/statuses/12345

En outre, le format des représentations est lui aussi indiqué dans l’URI (voir le “.json”) au lieu de profiter des puissants mécanismes de négociation de contenu fournis par HTTP. Ceci dit, les réponses retournées semblent proposer quelques URIs (n’oublions pas l’importance de l’hypermédia).

Exemple n°3 : Flickr

La documentation de l’API rappelle celle de Twitter par sa clarté et son découpage par ressources. Et là encore, le nom du service à invoquer est porté par un paramètre HTTP, nommé “method” et non par la méthode HTTP :

http://api.flickr.com/services/rest/?method=flickr.test.echo&…

Point intéressant, cette documentation donne sa propre vision de REST :

“REST est le format de requête le plus simple à utiliser”

Nous reviendrons plus tard sur cett vision de REST.

Exemple n°4 : Google

Là on est bien plus proche des principes de REST même si la notion de ressource ne ressort pas clairement :

http://ajax.googleapis.com/ajax/services/search/web?v=1.0&q=REST

En effet, l’URI /search/web fait davantage penser à une opération qu’à une ressource.

Exemple n°5 : Facebook

Il s’agit là encore d’un exemple d’API similaire aux précédentes, sur la transmission du nom du service et sur l’utilisation des seules méthodes GET et POST du protocole HTTP. Cependant la documentation se veut plus pragmatique :

“The API uses a REST-like interface. This means that our Facebook method calls are made over the internet by sending HTTP GET or POST requests”

On retrouve la vision de REST comme format de requête plus simple. Autre point intéressant, l’API est présentée comme REST-like et non comme RESTful, ce qui est déjà plus rigoureux (bien que moins marketing).

Exemple n°6 : Yahoo

Les APIs proposées par Yahoo sont assez proches des précédentes :

http://address.yahooapis.com/v1/action?format=format&params

où “action” désigne le nom du service à invoquer. On retrouve donc les mêmes anti-patterns concernant la transmission du nom du service et du format des représentations. Et un autre : le numéro de version du service est indiqué dans l’URI.

Yahoo met en avant la même vision de REST que ses confrères :

“The Yahoo! Search Web Services are all REST services. That means you can easily construct request URLs that will work in your browser, on the command line, and in your code”

Un peu de recul

Les APIs étudiées violent grosso modo les mêmes principes de REST. Ces anti-patterns tournent notamment autour de la notion d’URI qui est mal exploitée : l’URI est souvent utilisé comme fourre-tout permettant par exemple d’indiquer le nom du service à invoquer, sa version, ou le format des représentations, sans même faire apparaître la notion de ressource. Alors que l’URI a pour simple objectif d’adresser une ressource (n’oublions pas la définition de ce sigle : “Uniform Resource Identifier”) et que le protocole HTTP dispose de moyens efficaces pour gérer toutes les autres problématiques évoquées (notamment : interface uniforme, négociation de contenu).

Si vous avez tenu jusqu’ici alors je vous félicite et je vous remercie. Mais ne vous arrêtez pas là ! A ce stade vous devez penser que je ne jure que par REST mais je n’ai aucunement la prétention de rejeter toutes ces APIs. Si de tels éditeurs partagent les mêmes anti-patterns REST, c’est qu’il y a une bonne raison. Et cette raison, je la partage !

En effet : effectivement, toutes ces APIs ne respectent pas toutes les contraintes imposées par REST. Mais cela les rend-elles moins flexibles, moins scalables, moins simples à utiliser ? Non, pas nécessairement. En un mot il faut du pragmatisme ! Il est clair qu’aujourd’hui tout éditeur qui se veut “high-tech” se doit de proposer une API dite “RESTful” pour des raisons marketing évidentes. Même si cette API est en réalité plutôt “REST-like” comme osent toutefois le préciser certains d’entre eux. C’est la simplicité qui est et qui doit être (justement) mise en avant et il ne faut simplement pas tomber dans le piège tendu par le marketing.

Toutes ces APIs ne sont pas RESTful. OK. Mais en pratique cela ne nuit pas à leur succès. Une API RESTful a des avantages. Mais cela ne signifie pas que seules les APIs RESTful ont ces avantages. En outre, je vous mets au défi de trouver une API réellement RESTful ;-)

Comment Form