Devo usar o WADL para descrever minha API RESTful?

Estou prestes a embarcar em um projeto que faz uso extensivo de uma abordagem RESTful adequadamente. Ou seja, ele usa o HATEOAS e fornece recursos de uma maneira que permite a exploração geral por um cliente.

Gostaria de garantir que forneça uma descrição dos meus pontos de extremidade de uma maneira que permita que os aplicativos clientes sejam gerados automaticamente em uma ampla variedade de idiomas. Entendo que, para serviços Web baseados em SOAP, posso usar o WSDL e que, aparentemente, existe o WSDL2 que fornece uma maior definição dos verbos HTTP em uso com o REST. No entanto, vejo muitos artigos balançando para frente e para trás sobre sua utilidade.

Portanto, devo usar o WADL para permitir que os geradores de código externos construam rapidamente um cliente para o meu aplicativo da Web ou há um padrão melhor esperado?

Meu conselho é não se incomodar. O WADL não foi tão amplamente adotado Veja esta pergunta no Stack Overflow e há algumas opiniões fortes de que ele não se encaixa no tipo de REST 'adequado' que você descreve, como mostrado aqui em outra questão do Stack Overflow .

As descrições de WADL são demoradas para serem construídas (e principalmente manuais) e adicionam uma fragilidade que o HATEOAS foi projetado para evitar - ou seja, você terá alguns pontos de entrada bem definidos, mas exatamente como o cliente avança é então determinado por links opacos, não predefinidos. 'contrato'.

Isso não quer dizer que você deva fugir totalmente da documentação, definição de esquema etc., embora exista um fim no espectro RESTifarian que sugira que você possa abordar um nível tão alto de auto-descrição que não precise deles. Não achei que fosse esse o caso na prática. Alguns exemplos sólidos de trabalho devem ser todas as necessidades de um desenvolvedor desconhecido. E conecte alguns clientes para sua própria API para experimentá-la (bastante fácil no JQuery). Isso lhe dará uma boa indicação se você está construindo algo consumível ou não.

Uma boa fonte de informações nessa área é a linguagem de aplicativos de hipertexto . Acho algumas delas um pouco pesadas, mas os debates na lista de discussão são bons, atuais e relevantes.

Espero que ajude você a começar.

O estado das interfaces REST conduzidas a partir de algo que não seja um navegador interativo não é muito bom. HATEOAS é um princípio legal, mas leva a interfaces muito fortemente orientadas para as pessoas e tende a levar o ônus da interface do usuário a ser colocada no desenvolvedor de serviços (que geralmente está bastante ocupado fazendo o serviço em si).

A própria WADL não é muito boa; ele realmente não captura o suficiente da semântica do serviço para possibilitar a criação de ferramentas. Obviamente, esse é um problema difícil em geral. O WSDL também raramente expõe informações suficientes, e isso teve muito mais esforço no problema (é possível anexar informações suficientes, mas quase ninguém o faz).

No entanto, está dizendo que um colega meu passou meses trabalhando em uma biblioteca que usa uma interface REST para um serviço, e a interface descrita pelo WSDL para o mesmo serviço ^[*] foi usada automaticamente para quase a mesma qualidade em segundos; o resto do caminho foi sobre um dia de aulas de embrulho. Meu palpite (baseado em um tamanho de amostra limitado) é que você não pode se livrar de toda fragilidade em um serviço complexo, porque a semântica do serviço evoluirá inevitavelmente ao longo do tempo e que o REST é melhor na interface de humanos, enquanto o SOAP é melhor para bibliotecas de interface (há boas ferramentas de cliente WSDL / SOAP para quase todos os idiomas importantes). A menos que você tenha o luxo de fazer as duas coisas, qual delas focar deve depender do conjunto de clientes mais importante para você.

Eu não colocaria muito esforço na WADL, mas se sua estrutura REST a produzir para você (o Apache CXF faz isso), não haverá um motivo específico para não fornecê-la. Qualquer pessoa que queira utilizar seu código com ferramentas desejará WSDL + SOAP.

^{[*] Como autor do serviço em questão, posso dizer com certeza que ambas as interfaces suportaram as mesmas operações - havia um modelo abstrato subjacente comum - e em um estilo "natural" para os dois tipos de interface. No lado do serviço, definitivamente era o caso de algumas coisas serem mais fáceis com o REST e outras com o SOAP.}

O W3C fez uma recomendação formal para um padrão de documentação REST baseado no WSDL 2.0 . Aqui está uma citação do artigo da IBM :

O termo serviços da Web geralmente é associado a serviços baseados em operação ou ação usando os padrões SOAP e WS *, como WS-Addressing e WS-Security. O termo serviços da Web REST geralmente se refere a uma arquitetura de serviços da Web baseada em recursos que usa HTTP e XML. Cada um desses estilos arquitetônicos de serviço da Web tem seu lugar, mas até recentemente, o padrão WSDL não suportava igualmente os dois estilos. A ligação HTTP do WSDL 1.1 era inadequada para descrever as comunicações com HTTP e XML; portanto, não havia como descrever formalmente os serviços da Web REST com o WSDL. A publicação do WSDL 2.0, que foi projetada com os serviços da Web REST em mente, como uma recomendação do World Wide Web Consortium (W3C) significa que agora existe um idioma para descrever os serviços da Web REST.