¿Debo usar WADL para describir mi API RESTful?

Estoy a punto de embarcarme en un proyecto que hace un uso extensivo de un enfoque adecuadamente RESTful. Es decir, utiliza HATEOAS y sirve recursos de una manera que permite la exploración general por parte de un cliente.

Me gustaría asegurarme de proporcionar una descripción de mis puntos finales de manera que permita que las aplicaciones del cliente se generen automáticamente en una amplia variedad de idiomas. Entiendo que para los servicios web basados ​​en SOAP puedo usar WSDL y que aparentemente hay WSDL2 que proporciona una mayor definición de los verbos HTTP en uso con REST. Sin embargo, veo muchos artículos que se mueven de un lado a otro sobre su utilidad.

Entonces, ¿debería usar WADL para permitir que los generadores de código externos construyan rápidamente un cliente para mi aplicación web o hay un mejor estándar que se espera?

Mi consejo es no molestarse. WADL no ha sido tan ampliamente adoptado. Vea esta pregunta sobre Stack Overflow y hay algunas opiniones sólidas de que no encaja bien con el tipo de RESTO 'adecuado' que describe, como se muestra aquí en otra pregunta de Stack Overflow .

Las descripciones de WADL requieren mucho tiempo para crear (y en su mayoría manuales) y agregan una fragilidad que HATEOAS está diseñada para evitar, es decir, tendrá algunos puntos de entrada bien definidos, pero la forma exacta en que su cliente procede se determina mediante enlaces opacos, no predefinidos. 'contrato'.

Eso no quiere decir que deba huir por completo de la documentación, la definición del esquema, etc., aunque hay un final del espectro RESTifarian que sugeriría que puede acercarse a un nivel tan alto de autodescripción que no los necesita. No he encontrado que este sea el caso en la práctica. Algunos ejemplos sólidos y trabajados deberían ser todo lo que un desarrollador desconocido necesita. Y obtenga algunos clientes para su propia API para probarlo (lo suficientemente fácil desde JQuery). Eso le dará una buena indicación de si está construyendo algo consumible o no.

Una buena fuente de información en esta área es el lenguaje de aplicación de hipertexto . Algunos me parecen un poco pesados, pero los debates en la lista de correo son buenos, actuales y relevantes.

Espero que te ayude a comenzar.

El estado de las interfaces REST como conducidas desde cualquier cosa que no sea un navegador interactivo no es muy bueno. HATEOAS es un buen principio, pero conduce a interfaces que están muy orientadas a las personas y tiende a llevar la carga de la interfaz de usuario al desarrollador del servicio (que generalmente está bastante ocupado haciendo que el servicio funcione).

WADL en sí no es demasiado bueno; en realidad no capta la semántica suficiente del servicio para que sea posible mejorar las cosas. Por supuesto, este es un problema difícil en general. WSDL rara vez expone suficiente información, y se ha puesto mucho más esfuerzo en el problema (es posible adjuntar suficiente información, pero casi nadie realmente lo hace).

Sin embargo, es revelador que un colega mío haya pasado meses trabajando en una biblioteca que utiliza una interfaz REST para un servicio, y la interfaz descrita por WSDL para el mismo servicio ^[*] se trabajó automáticamente con casi la misma calidad en segundos; El resto del camino consistió en un día de escribir clases de envoltura. Mi presentimiento (basado en un tamaño de muestra limitado) es que no puede deshacerse de toda fragilidad en un servicio complejo porque la semántica del servicio evolucionará inevitablemente con el tiempo, y que REST es mejor para manejar interfaces para humanos mientras SOAP es mejor para bibliotecas de interfaz (hay buenas herramientas de cliente WSDL / SOAP para casi todos los idiomas notables). A menos que tenga el lujo de hacer ambas cosas, en cuál enfocarse dependerá del grupo de clientes que más le interese.

No pondría mucho esfuerzo en WADL, pero si su marco REST lo producirá para usted (Apache CXF hace esto), entonces no hay ninguna razón particular para no proporcionarlo. Cualquiera que quiera quitarle el código a su herramienta querrá WSDL + SOAP.

^{[*] Como autor del servicio en cuestión, puedo decir con certeza que ambas interfaces admitían las mismas operaciones (había un modelo abstracto subyacente común) y en un estilo "natural" para ambos tipos de interfaz. Del lado del servicio, definitivamente fue el caso de que algunas cosas fueron más fáciles con REST y otras con SOAP.}

El W3C ha hecho una recomendación formal para un estándar de documentación REST basado en WSDL 2.0 . Aquí hay una cita del artículo de IBM :

El término servicios web generalmente se asocia con servicios basados ​​en operaciones o acciones que utilizan SOAP y los estándares WS *, como WS-Addressing y WS-Security. El término servicios web REST generalmente se refiere a una arquitectura de servicios web basada en recursos que utiliza HTTP y XML. Cada uno de estos estilos arquitectónicos de servicios web tiene su lugar, pero hasta hace poco, el estándar WSDL no era compatible con ambos estilos. El enlace HTTP WSDL 1.1 era inadecuado para describir las comunicaciones con HTTP y XML, por lo que no había forma de describir formalmente los servicios web REST con WSDL. La publicación de WSDL 2.0, que fue diseñada teniendo en cuenta los servicios web REST, como una recomendación del Consorcio World Wide Web (W3C) significa que ahora hay un lenguaje para describir los servicios web REST.