Ne communiquez pas sur votre API en disant qu'elle est RESTful. Ceci est un des conseils donnés par des développeurs d'APIs lors d'un épisode récent du Nodeup podcast - an APIs show. On peut entendre dans ce podcast une conversation entre Daniel Shaw, ingénieur chez Voxer et hôte de cet évènement, James Halliday, fondateur de Browserling et les invités Mark Cavage et Andrew Sliwinski. Cavage est un ingénieur en développement pour le fournisseur d'infrastructure Cloud Joyent et auteur du package Node.js Restify. Joyent supporte le projet Node.js et l'utilise de façon intensive. Sliwinski est le cofondateur et CTO du site DIY, dédié au partage d'expériences pour les enfants.
Attaquant par le sujet de la conception des APIs, la conversation serpente entre les problématiques clés du développement d'APIs avec Node.js, en questionnant en particulier la valeur de REST, la sécurité, le test, la documentation, les schémas et le streaming. La méthode de conception favorite des participants est "de commencer par le fichier d'information, le README". On conseille d'aborder la conception des APIs comme on construit une interface utilisateur. Cavage fait référence à la façon d'Amazon.com d'aborder le développement produit en "écrivant le communiqué de presse d'abord". Il ajoute que vous pouvez commencer en construisant une API minimale, pour ensuite la faire évoluer en fonction de l'expérience, à l'utilisation. N'essayez pas d'inclure trop de fonctionnalités à priori.
La valeur de REST est considérée comme mitigée. Le problème avec le fait de communiquer sur son API comme étant RESTful, c'est que, d'après Daniel Shaw, cela "agit comme un appât à troll". Les gens sont trop obsédés et pédants au sujet de la conformité avec REST. Il est plus important d'être exigent au sujet d'HTTP, car c'est le protocole sous-jacent commun. Le conseil de Mark Cavage est qu'HTTP devrait être "l'interface à utiliser aux frontières, au niveau du firewall", mais que, en interne, il vaut mieux se rabattre sur les formats de données et les modes de transport les plus efficaces, car "HTTP a un coût". Il cite dnode et fast comme exemples de Frameworks RPC qu'ils utilisent dans les infrastructures "back-end".
Le sujet de la sécurité fait débat. Halliday et Shaw ont le sentiment que les nouveaux protocoles comme Oauth sont devenus un frein à l'enthousiasme initial de pouvoir consommer les APIs avec des outils en ligne de commande comme curl. Cependant, Cavage réplique que la sécurité doit être alignée avec la valeur de l'API à protéger et qu'une authentification HTTP basique est souvent insuffisante. Cavage introduit les Signatures HTTP qui, pour lui, sont meilleures que les mots de passe et "plus simples que les autres protocoles". Les signatures HTTP ajoutent l'authentification d'origine, l'intégrité des messages et la résistance aux attaques par rejeu des requêtes HTTP. Développées par Joyent, les signatures HTTP ont récemment été soumises à l'IETF.
Tous sont d'accord sur l'idée que les tests devraient s'appuyer sur des systèmes et des données réels et que le recours à des "mocks" est une mauvaise pratique. Le problème avec les mocks est que les tests deviennent déconnectés de la réalité, explique Halliday. Sliwinski décrit comment chez DIY, ils remplissent une base de données locale de données "live" pour leurs tests d'intégration continue, donc sans recours à des mocks. Parmi les outils utilisés se trouvent Nodeunit, Tap et Travis CI.
Au sujet de la documentation, Cavage plaisante en disant que WSDL gagne par son "nombre de points d'inaptitude". Chez DIY, ils écrivent la documentation des APIs en premier lieu, sous un format de spécification JSON pilotant une page web de documentation interactive. Cavage décrit comment Joyent utilise Restdown pour documenter leurs APIs et garde cette documentation dans le repository hébergeant l'API. Garder la documentation en ligne avec l'API est un défi important et tout le monde s'accorde sur l'idée de préférer une documentation interactive avec des données d'exemple.
Les schémas sont un autre domaine problématique. Les deux problèmes principaux avec les validateurs de schémas sont qu'ils sont lents et qu'ils retournent des erreurs imprécises, explique Cavage. Mais d'un autre côté, le faire à la main, sans grammaire formelle, est risqué. DIY utilise JSON Schema mais en faisant des compromis. Le standard est toujours en évolution et aucune implémentation de validateur de schéma JSON pour Node.js ne sort du lot. Sliwinski dit qu'ils ont été chanceux avec JSV bien qu'ils aient eu à écrire leurs propres wrappers pour attraper et réinterpréter les messages d'erreurs obtus.
Le podcast comprend une longue discussion autour des APIs de streaming tirant profit de l'architecture d'I/O non-bloquantes de Node.js. Halliday explique que le streaming JSON pour les APIs est tout à fait sensé, dans l'optique d'éviter le buffering et réduire la latence. Cavage note que le support du streaming JSON est une des raisons principales d'utiliser Restify plutôt que le package Express. Il faut être prudent quant à l'utilisation des middlewares Node.js avec du streaming JSON. Cavage aime utiliser des middlewares tels que Connect pour prendre en charge la "complexité venant du monde de l'utilisateur", comme les sessions et différents aléas provenant du client mais il rappelle que c'est au prix de la perte du support du streaming. Utiliser Node.js pur, sans middleware, est plus efficace pour la prise en charge native des flux.
Mais revenons à la question initiale : est-il sain de communiquer sur son API comme étant RESTful ou est-ce que cela encourage les comportements préjudiciables de la part des pédants ? REST est-il un standard à appliquer ou est-ce un ensemble de contraintes ? Où placez-vous la limite entre ce qui est RESTful et ce qui ne l'est pas ? Nous aimerions entendre votre expérience.