Devo usare WADL per descrivere la mia API RESTful?

Il mio consiglio è di non disturbare. WADL non è stato ampiamente adottato Vedi questa domanda su Stack Overflow e ci sono alcuni punti di forza non è una buona idea con il tipo di REST "appropriato" che descrivi, come mostrato qui in un'altra domanda di overflow dello stack .

Le descrizioni WADL richiedono molto tempo per essere compilate (e soprattutto manuali) e aggiungono una fragilità che HATEOAS è progettata per evitare - ovvero avrai alcuni punti di ingresso ben definiti ma esattamente come procede il cliente viene quindi determinato da collegamenti opachi, non un "contratto" predefinito.

Questo non vuol dire che dovresti scappare interamente dalla documentazione, dalla definizione dello schema, ecc., anche se c'è una fine dello spettro RESTifarian che suggerirebbe di poter accedere ad un livello così alto di auto-descrizione che non ti serve. Non ho trovato questo in pratica. Alcuni esempi solidi dovrebbero essere tutti requisiti di sviluppo non familiari. E scarica alcuni client per la tua API per provarlo (abbastanza facile da JQuery). Ciò ti darà una buona indicazione se stai costruendo qualcosa di consumabile o meno.

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

Spero di aiutarti a iniziare.

Lo stato delle interfacce REST come guidato da qualcosa di diverso da un browser interattivo non è molto buono. HATEOAS è un buon principio, ma porta a interfacce strongmente orientate alle persone e tende a portare l'onere dell'interfaccia utente a essere messa sullo sviluppatore di servizi (che di solito è piuttosto impegnato a far funzionare il servizio stesso).

WADL non è troppo grande; in realtà non cattura abbastanza la semantica del servizio per rendere possibile l'elaborazione delle cose. Certo, questo è un problema difficile in generale. WSDL raramente espone anche abbastanza informazioni, e questo ha comportato uno sforzo molto maggiore nel problema (è possibile allegare informazioni sufficienti, ma praticamente nessuno lo fa).

Tuttavia, è stato detto che un mio collega ha passato 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 strumentata automaticamente quasi alla stessa qualità in pochi secondi; andare a fare il resto era circa un giorno di scrittura di classi di wrapping. La mia impressione (basata su una dimensione campionaria limitata) è che non è possibile eliminare 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 gli umani mentre SOAP è meglio per librerie di interfacce (esiste una buona strumentazione client WSDL / SOAP per quasi tutte le lingue di nota). A meno che tu non abbia il lusso di fare entrambe le cose, quale su cui concentrarsi dovrebbe dipendere da quale serie di clienti ti interessa di più.

Non metterei molto impegno in WADL, ma se il tuo framework REST lo produrrà per te (questo fa Apache CXF), non c'è alcun motivo particolare per non fornirlo. Chiunque voglia ritagliare il tuo 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 di base - e in uno stile "naturale" per entrambi i tipi di interfaccia . Dal lato del servizio, è stato sicuramente il caso che alcune cose fossero più semplici con REST e altre con SOAP.}

Il W3C ha formulato una raccomandazione formale per un standard della documentazione REST basato su WSDL 2.0 . Ecco una citazione dal articolo IBM :

The term Web services is typically associated with operation- or action-based services using SOAP and the WS* standards, such as WS-Addressing and WS-Security. The term REST Web services generally refers to a resource-based Web services architecture that uses HTTP and XML. Each of these architectural Web service styles has its place, but until recently, the WSDL standard didn't equally support both styles. The WSDL 1.1 HTTP binding was inadequate to describe communications with HTTP and XML, so there was no way to formally describe REST Web services with WSDL. The publication of WSDL 2.0, which was designed with REST Web services in mind, as a World Wide Web Consortium (W3C) recommendation means there is now a language to describe REST Web services.