Dovrei usare WADL per descrivere la mia API RESTful?

Sto per intraprendere un progetto che fa ampio uso di un approccio RESTful. Cioè, utilizza HATEOAS e serve risorse in un modo che consente l'esplorazione generale da parte di un client.

Vorrei assicurarmi di fornire una descrizione dei miei endpoint in modo da consentire la generazione automatica delle applicazioni client in un'ampia varietà di lingue. Comprendo che per i servizi Web basati su SOAP posso usare WSDL e che apparentemente esiste WSDL2 che fornisce una maggiore definizione dei verbi HTTP in uso con REST. Tuttavia vedo molti articoli oscillare avanti e indietro sulla sua utilità.

Quindi, dovrei usare WADL per consentire ai generatori di codice esterni di creare rapidamente un client per la mia applicazione Web o ci si aspetta uno standard migliore?

Il mio consiglio è di non disturbare. WADL non è stato così ampiamente adottato Vedi questa domanda su Stack Overflow e ci sono alcune idee forti che non si adattano al tipo di REST "corretto" che descrivi, come mostrato qui in un'altra domanda Stack Overflow .

Le descrizioni WADL richiedono molto tempo per essere costruite (e per lo più manuali) e aggiungono una fragilità che HATEOAS è progettata per evitare - cioè avrai alcuni punti di ingresso ben definiti ma esattamente come procede il tuo cliente è quindi determinato da collegamenti opachi, non predefiniti 'contrarre'.

Questo non vuol dire che dovresti scappare completamente dalla documentazione, dalla definizione dello schema, ecc., Anche se c'è una fine dello spettro RESTifarian che suggerirebbe che puoi avvicinarti a un livello così alto di auto-descrizione che non ti servono. Non ho trovato questo il caso in pratica. Alcuni esempi concreti dovrebbero essere tutte esigenze di sviluppatori sconosciuti. E fai cadere alcuni client per la tua API per provarlo (abbastanza facile da JQuery). Questo ti darà una buona indicazione se stai costruendo qualcosa di consumabile o meno.

Una buona fonte di informazioni in quest'area è il linguaggio dell'applicazione Hypertext . Ne trovo un po 'pesante, ma i dibattiti sulla mailing list sono buoni, attuali e pertinenti.

Spero che ti aiuti a iniziare.

Lo stato delle interfacce REST come guidato da qualcosa di diverso da un browser interattivo non è molto buono. HATEOAS è un bel principio, ma porta a interfacce fortemente orientate alle persone e tende a portare il carico dell'interfaccia utente a carico dello sviluppatore del servizio (che di solito è piuttosto impegnato a far funzionare il servizio stesso).

WADL stesso non è troppo grande; in realtà non cattura abbastanza della semantica del servizio per rendere possibile elaborare le cose. Naturalmente, questo è un problema difficile in generale. WSDL raramente espone abbastanza informazioni, e questo ha comportato molti più sforzi nel problema (è possibile allegare abbastanza informazioni, ma quasi nessuno lo fa davvero).

Eppure sta dicendo che un mio collega ha trascorso mesi a lavorare su una libreria che utilizza un'interfaccia REST per un servizio e che l'interfaccia descritta dallo WSDL per lo stesso servizio ^{[*] è} stata utilizzata automaticamente in quasi la stessa qualità in pochi secondi; andare avanti per il resto era circa una giornata di scrittura di lezioni di avvolgimento. Il mio sospetto (basato su una dimensione del campione limitata) è che non puoi liberarti di tutta la fragilità in un servizio complesso perché la semantica del servizio si evolverà inevitabilmente nel tempo e che REST è migliore nel guidare le interfacce per l'uomo mentre SOAP è meglio per librerie di interfaccia (esistono buoni strumenti client WSDL / SOAP per quasi tutte le lingue note). A meno che tu non abbia il lusso di fare entrambi, quello su cui concentrarti dovrebbe dipendere dal gruppo di clienti a cui tieni di più.

Non farei molti sforzi in WADL, ma se il tuo framework REST lo produrrà per te (Apache CXF lo fa), non c'è motivo particolare per non fornirlo. Chiunque desideri eliminare il codice, vorrà WSDL + SOAP.

^{[*] Come autore del servizio in questione, posso dire con certezza che entrambe le interfacce supportano le stesse operazioni - c'era un modello astratto sottostante comune - e in uno stile "naturale" per entrambi i tipi di interfaccia. Per quanto riguarda il servizio, è stato sicuramente il caso che alcune cose fossero più facili con REST e altre con SOAP.}

Il W3C ha formulato una raccomandazione formale per uno standard di documentazione REST basato su WSDL 2.0 . Ecco una citazione dall'articolo IBM :

Il termine servizi Web è in genere associato a servizi basati su operazioni o azioni che utilizzano SOAP e gli standard WS *, come WS-Addressing e WS-Security. Il termine servizi Web REST si riferisce generalmente a un'architettura di servizi Web basata su risorse che utilizza HTTP e XML. Ognuno di questi stili di servizi Web architetturali ha il suo posto, ma fino a poco tempo fa lo standard WSDL non supportava entrambi gli stili. L'associazione HTTP WSDL 1.1 non era adeguata per descrivere le comunicazioni con HTTP e XML, quindi non c'era modo di descrivere formalmente i servizi Web REST con WSDL. La pubblicazione di WSDL 2.0, progettata pensando ai servizi Web REST, come raccomandazione del World Wide Web Consortium (W3C) significa che esiste ora un linguaggio per descrivere i servizi Web REST.