Dois-je utiliser WADL pour décrire mon API RESTful?
Je suis sur le point de me lancer dans un projet qui utilise largement une approche correctement RESTful. Autrement dit, il utilise HATEOAS et sert les ressources d'une manière qui permet une exploration générale par un client.
Je voudrais m'assurer de fournir une description de mes points de terminaison d'une manière qui permettrait aux applications client d'être générées automatiquement dans une grande variété de langues. Je comprends que pour SOAP services Web basés, je peux utiliser WSDL et qu'apparemment il y a WSDL2 qui fournit une meilleure définition des verbes HTTP utilisés avec REST. Cependant, je vois de nombreux articles se balancer d'avant en arrière sur c'est l'utilité.
Alors, dois-je utiliser WADL pour permettre aux générateurs de code externes de créer rapidement un client pour mon application Web ou existe-t-il un meilleur standard attendu?
Mon conseil est de ne pas déranger. WADL n'a pas été aussi largement adopté Voir cette question sur Stack Overflow et il y a des opinions fortes qui ne correspondent pas au type de 'bon' REST you décrire, comme montré ici sur une autre question Stack Overflow .
Les descriptions WADL sont longues à construire (et principalement manuelles) et elles ajoutent une fragilité que HATEOAS est conçue pour éviter - c'est-à-dire que vous aurez des points d'entrée bien définis, mais la façon dont votre client procède est ensuite déterminée par des liens opaques, pas un lien prédéfini 'Contrat'.
Cela ne veut pas dire que vous devriez fuir entièrement la documentation, la définition de schéma, etc., bien qu'il y ait une fin du spectre RESTifarian qui suggérerait que vous pouvez approcher un niveau si élevé d'auto-description que vous n'en avez pas besoin. Je n'ai pas trouvé que c'était le cas dans la pratique. Quelques exemples solides devraient être tout ce dont un développeur inconnu a besoin. Et associez quelques clients à votre propre API pour l'essayer (assez facile à partir de JQuery). Cela vous donnera une bonne indication si vous construisez quelque chose de consommable ou non.
Une bonne source d'informations dans ce domaine est le Hypertext Application Language . J'en trouve une partie un peu lourde, mais les débats sur la liste de diffusion sont bons et actuels et pertinents.
J'espère que cela vous aidera à démarrer.
L'état des interfaces REST telles que pilotées par autre chose qu'un navigateur interactif n'est pas très bon. HATEOAS est un bon principe, mais il conduit à des interfaces très fortement orientées vers les personnes et il tend à pour entraîner la charge de l'interface utilisateur sur le développeur du service (qui est généralement assez occupé à faire fonctionner le service lui-même).
WADL lui-même n'est pas trop grand; il ne capture pas suffisamment la sémantique du service pour permettre un outillage. Bien sûr, c'est un problème difficile en général. WSDL expose rarement suffisamment d'informations non plus, et cela a demandé beaucoup plus d'efforts (il est possible de joindre suffisamment d'informations, mais presque personne ne le fait réellement).
Pourtant, il est révélateur qu'un de mes collègues a passé des mois à travailler sur une bibliothèque qui utilise une interface REST pour un service, et l'interface décrite par WSDL pour le même service[*] a été usiné automatiquement à presque la même qualité en quelques secondes; faire le reste du chemin était une journée d'écriture de cours d'emballage. Mon intuition (basée sur une taille d'échantillon limitée) est que vous ne pouvez pas vous débarrasser de toute fragilité dans un service complexe, car la sémantique du service évoluera inévitablement au fil du temps, et cela REST est meilleur à piloter des interfaces pour les humains tout en SOAP est meilleur pour les bibliothèques d'interfaces (il existe de bons outils client WSDL/SOAP pour presque tous les langages à noter). À moins que vous n'ayez le luxe de faire les deux, lequel choisir la concentration devrait dépendre de l'ensemble des clients dont vous vous souciez le plus.
Je ne mettrais pas beaucoup d'efforts dans WADL, mais si votre framework REST le produira pour vous (Apache CXF le fait)), il n'y a aucune raison particulière de ne pas le fournir. Quiconque veut utiliser l'outil off votre code voudra WSDL + SOAP.
[*] En tant qu'auteur du service en question, je peux dire avec certitude que les deux interfaces supportaient les mêmes opérations - il y avait un modèle abstrait sous-jacent commun - et dans un style "naturel" pour les deux types d'interfaces. Côté service, il était certain que certaines choses étaient plus faciles avec REST et d'autres avec SOAP.
Le W3C a fait une recommandation formelle pour une norme de documentation REST basée sur WSDL 2.0 . Voici une citation de l'article IBM :
Le terme services Web est généralement associé à des services basés sur des opérations ou des actions utilisant SOAP et les normes WS *, telles que WS-Addressing et WS-Security. Le terme REST Les services Web font généralement référence à une architecture de services Web basée sur les ressources qui utilise HTTP et XML. Chacun de ces styles de services Web architecturaux a sa place, mais jusqu'à récemment, la norme WSDL ne prenait pas également en charge les deux styles. Le WSDL 1.1 La liaison HTTP était inadéquate pour décrire les communications avec HTTP et XML, il n'y avait donc aucun moyen de décrire formellement REST services Web avec WSDL. La publication de WSDL 2.0, conçue avec REST Services Web à l'esprit, en tant que recommandation du World Wide Web Consortium (W3C), il existe désormais un langage pour décrire REST Services Web .