Sollte ich WADL verwenden, um meine RESTful-API zu beschreiben?

Ich bin dabei, ein Projekt in Angriff zu nehmen, das einen angemessenen REST-Ansatz in großem Umfang nutzt. Das heißt, es verwendet HATEOAS und stellt Ressourcen auf eine Weise bereit , die eine allgemeine Untersuchung durch einen Kunden ermöglicht.

Ich möchte sicherstellen, dass ich meine Endpunkte so beschreibe, dass Clientanwendungen automatisch in einer Vielzahl von Sprachen generiert werden können. Ich verstehe, dass ich für SOAP-basierte Webdienste WSDL verwenden kann und dass es anscheinend WSDL2 gibt, das eine bessere Definition der mit REST verwendeten HTTP-Verben bietet. Jedoch sehe ich viele Artikel, die hin und her schwingen, über seinen Nutzen.

Soll ich WADL verwenden , um externen Codegeneratoren das schnelle Erstellen eines Clients für meine Webanwendung zu ermöglichen, oder gibt es einen besseren Standard, der erwartet wird?

Mein Rat ist nicht zu stören. WADL ist noch nicht so weit verbreitet. Sehen Sie sich diese Frage zum Stapelüberlauf an und es gibt einige überzeugende Ansichten, die nicht gut zu der Art von 'richtigem' REST passen, die Sie beschreiben, wie hier in einer anderen Frage zum Stapelüberlauf gezeigt .

Die Erstellung von WADL-Beschreibungen ist zeitaufwändig (und meistens manuell). Sie erhöhen die Sprödigkeit, die durch HATEOAS vermieden werden soll. Das heißt, Sie haben einige genau festgelegte Einstiegspunkte. Wie Ihr Kunde dann vorgeht, hängt von undurchsichtigen Links ab, nicht von vordefinierten 'Vertrag'.

Das soll nicht heißen, dass Sie der Dokumentation, der Schemadefinition usw. völlig aus dem Weg gehen sollten, obwohl es ein Ende des RESTifarian-Spektrums gibt, das darauf hindeutet, dass Sie sich einem so hohen Grad an Selbstbeschreibung nähern können, dass Sie sie nicht benötigen. Ich habe nicht festgestellt, dass dies in der Praxis der Fall ist. Einige solide ausgearbeitete Beispiele sollten alle unbekannten Entwickleranforderungen erfüllen. Und stellen Sie ein paar Clients für Ihre eigene API bereit, um es auszuprobieren (einfach genug von JQuery). Das gibt Ihnen einen guten Hinweis darauf, ob Sie etwas Verbrauchbares bauen oder nicht.

Eine gute Informationsquelle in diesem Bereich ist die Hypertext Application Language . Ich finde einige davon ein wenig schwergewichtig, aber die Debatten auf der Mailingliste sind gut und aktuell und relevant.

Hoffe das hilft dir beim Einstieg.

Der Status von REST-Schnittstellen, die nicht über einen interaktiven Browser gesteuert werden, ist nicht sehr gut. HATEOAS ist ein nettes Prinzip, aber es führt zu Benutzeroberflächen, die sehr stark personenorientiert sind, und es führt dazu, dass die Benutzeroberfläche dem Serviceentwickler auferlegt wird (der normalerweise ziemlich beschäftigt ist, den Service selbst zum Laufen zu bringen).

WADL selbst ist nicht zu groß; Es wird nicht genug von der Semantik des Dienstes erfasst, um es zu ermöglichen, die Dinge zu verbessern. Natürlich ist dies im Allgemeinen ein schwieriges Problem. WSDL stellt selten genug Informationen zur Verfügung, und das ist mit viel mehr Aufwand verbunden (es ist möglich, genügend Informationen beizufügen, aber kaum jemand tut dies tatsächlich).

Es ist jedoch bezeichnend, dass ein Kollege von mir monatelang an einer Bibliothek gearbeitet hat, die eine REST-Schnittstelle für einen Service verwendet, und die von WSDL beschriebene Schnittstelle für denselben Service ^[*] wurde in Sekundenschnelle automatisch auf nahezu dieselbe Qualität umgerüstet. Der Rest des Weges war ungefähr ein Tag, an dem Wrapping-Kurse geschrieben wurden. Meine Vermutung (basierend auf einer begrenzten Stichprobengröße) ist, dass Sie in einem komplexen Dienst nicht alle Sprödigkeit beseitigen können, da sich die Semantik des Dienstes im Laufe der Zeit zwangsläufig weiterentwickelt und REST beim Fahren von Schnittstellen für Menschen besser ist, während SOAP für besser ist Schnittstellenbibliotheken (es gibt gute WSDL / SOAP-Client-Tools für fast alle wichtigen Sprachen). Wenn Sie nicht den Luxus haben, beides zu tun, hängt es von der Gruppe der Kunden ab, die Sie am meisten interessieren.

Ich würde WADL nicht viel Mühe geben, aber wenn Ihr REST-Framework es für Sie produzieren wird (Apache CXF tut dies), gibt es keinen besonderen Grund, es nicht bereitzustellen. Jeder, der Ihren Code ausbessern möchte, möchte WSDL + SOAP.

^{[*] Als Autor des fraglichen Dienstes kann ich mit Sicherheit sagen, dass beide Schnittstellen dieselben Operationen unterstützten - es gab ein gemeinsames zugrunde liegendes abstraktes Modell - und für beide Schnittstellentypen einen „natürlichen“ Stil. Auf der Serviceseite war es definitiv so, dass einige Dinge mit REST und andere mit SOAP einfacher waren.}

Das W3C hat eine formelle Empfehlung für einen auf WSDL 2.0 basierenden REST-Dokumentationsstandard abgegeben . Hier ist ein Zitat aus dem IBM-Artikel :

Der Begriff "Webdienste" wird in der Regel mit betriebs- oder aktionsbasierten Diensten verknüpft, die SOAP und die WS * -Standards verwenden, z. B. WS-Adressierung und WS-Sicherheit. Der Begriff REST-Webdienste bezieht sich im Allgemeinen auf eine ressourcenbasierte Webdienstarchitektur, die HTTP und XML verwendet. Jeder dieser Architektur-Webdienststile hat seinen Platz, aber bis vor kurzem unterstützte der WSDL-Standard nicht beide Stile gleichermaßen. Die HTTP-Bindung von WSDL 1.1 reichte nicht aus, um die Kommunikation mit HTTP und XML zu beschreiben. Daher gab es keine Möglichkeit, REST-Webdienste mit WSDL formal zu beschreiben. Die Veröffentlichung von WSDL 2.0, das im Hinblick auf REST-Webdienste als Empfehlung des World Wide Web Consortium (W3C) konzipiert wurde, bedeutet, dass es jetzt eine Sprache zur Beschreibung von REST-Webdiensten gibt.