Récemment, Mark Baker a tweeté au sujet d'une API REST de Nokia, dont le projet est sur github :
Il cite en particulier la section de documentation suivante :
Un des plus gros avantages constatés est que l'API devient elle-même la documentation de l'API :
- Sans HATEOAS, les développeurs devraient récupérer la donnée, se reporter à une documentation et essayer de comprendre comment construire la requête suivante.
- Avec HATEOAS, les développeurs apprennent quelles sont les prochaines actions disponibles.
Steve Jones, de CapGemini, a rebondi là-dessus dans un billet de blog récent :
Ces arguments me feraient vous virer, je pense. Je suis un grand fan de la documentation et je suis un grand fan de conception. Ce dont je ne suis pas du tout grand fan, c'est des gens faisant du processus de conception un ensemble d'étapes abstraites où la seule chose qui compte, c'est l'étape suivante.
Steve a évoqué auparavant que pour lui, l'IT favorisait la technologie par rapport à la réflexion et il déclare ici que, d'une certaine façon, le texte de Nokia permet d'illustrer à nouveau cet avis : la réflexion et la conception, dans l'IT, sont morts ou en bonne voie de l'être. Il pense qu'il y a des personnes qui n'accordent plus aucune valeur à la conception et qui la déconsidèrent continuellement en tant qu'activité importante du processus de développement.
Soyons clairs, avoir de la documentation à disposition est important. Ce qui serait dommage serait :
- d'avoir à attendre que quelqu'un fasse une application avant que je puisse commencer à écrire un client pour celle-ci.
- de disposer d'une documentation labyrinthique et sinueuse où l'on ne pourrait voir qu'une étape en avance.
D'après Steve, il y a une poussée des solutions "code-centric", passant devant les solutions "design-centric", en particulier autour de REST et HATEOAS. Avoir des APIs documentées pour les services permet au concepteur de cartographier non seulement ce qu'il veut faire mais aussi comment il veut le faire, et ce avant que le service ait été implémenté. Steve indique qu'avec l'approche susmentionnée (REST), un concepteur a besoin de passer continuellement de l'API au code et à de la pseudo-conception. Ce qui est au minimum inefficace. De ce qu'il constate en entreprise, il déclare que cette tendance actuelle est en train de retarder l'IT et impacter la maintenabilité des solutions REST et autres.
Ceci est une part de mes objections à REST : le manque de travail préalable à l'implémentation. Si j'ai deux équipes séparées, une côté client et une côté serveur, je ne veux pas à avoir à conduire un projet en waterfall où "le service est terminé, le client peut commencer". Et s'il s'agit d'équipes de sociétés différentes, je veux être capable de savoir qui s'est planté, je ne veux pas d'un cycle continu de "regardez dans la réponse à votre appel" et "mais c'était différent hier !". En d'autres termes, je voudrais que les gens puissent prévoir ce qu'ils vont fournir.
Steve Jones n'est pas contre l'utilisation de REST au moment de l'implémentation, toutefois. Il trouve simplement que les approches actuelles qu'il rencontre (l'API Nokia est un exemple) ne sont d'aucune aide lors des phases de conception et que celles-ci conduisent à une approche dite du marchand ambulant :
Si je ne connais pas la route pour aller au but et que je ne procède qu'un pas après l'autre pour prendre des décisions sur le chemin qui semble être le plus rapide, alors je ne recherche pas du tout l'efficacité de l'ensemble mais uniquement la façon la plus facile de passer à la prochaine étape.
Une des personnes ayant laissé un commentaire sur le blog de Steve ajoute le point suivant à la discussion :
Je vois des choses similaires avec les API exposées publiquement, que ça soit avec REST, une librairie ou autre. Les développeurs ont adopté l'idée (la bonne idée) de suivre des cycles très courts et l'appliquent à tout ce qu'ils font. Tout se retrouve dans des itérations et, allez savoir pourquoi, les développeurs se mettent à penser que la conception préalable, "upfront", n'est pas importante ou même une mauvaise chose. Lorsque l'on travaille derrière une API, la conception de style "evolutionary design" est plus acceptable. Mais les APIs publiques doivent être plus ou moins correctes à la sortie. Elles peuvent évoluer d'une certaine façon (par exemple, par extension) mais les refactorings créent une gêne considérable pour les utilisateurs.
Steve appelle à élaborer autour de REST une pratique standard de documentation des APIs RESTful, accompagnée d'un environnement d'exécution "bac à sable" comme le propose un autre commentateur, et de ne surtout pas compter uniquement sur HATEOAS.