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 des 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 les services Web basés sur SOAP, 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 son 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 points de vue convaincants que ce n'est pas un bon ajustement avec le type de `` bon '' REST que vous décrivez, comme indiqué 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, et non pas prédéfinis '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 langage d'application hypertexte . J'en trouve certains un peu lourds, mais les débats sur la liste de diffusion sont bons, actuels et pertinents.

J'espère que cela vous aidera à démarrer.

L'état des interfaces REST comme piloté 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 a tendance à faire peser 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 assez 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 vers un service, et l'interface décrite par WSDL vers le même service ^{[*] a} été conçue automatiquement pour presque la même qualité en quelques secondes; aller le reste du chemin était sur 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 parce que la sémantique du service évoluera inévitablement au fil du temps, et que REST est meilleur pour piloter des interfaces pour les humains tandis que SOAP est meilleur pour bibliothèques d'interface (il existe de bons outils client WSDL / SOAP pour presque toutes les langues importantes). À moins que vous n'ayez le luxe de faire les deux, celui sur lequel vous concentrer devrait dépendre de l'ensemble des clients qui vous intéressent le plus.

Je ne mettrais pas beaucoup d'efforts dans WADL, mais si votre framework REST le produit pour vous (Apache CXF le fait), il n'y a aucune raison particulière de ne pas le fournir. Toute personne qui souhaite utiliser 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 formulé 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 services Web REST fait 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. La liaison HTTP WSDL 1.1 était inadéquate pour décrire les communications avec HTTP et XML, il n'y avait donc aucun moyen de décrire formellement les services Web REST avec WSDL. La publication de WSDL 2.0, qui a été conçue en pensant aux services Web REST, en tant que recommandation du World Wide Web Consortium (W3C) signifie qu'il existe désormais un langage pour décrire les services Web REST.