REST e o WSDL

Há algum tempo, eu escrevi um artigo sobre como expor serviços construídos em WCF através do modelo REST, e além disso, foi comentado também sobre as principais diferenças no modelo REST com SOAP, apontando as características de cada uma deles. Um dos detalhes que ficou para trás foi o documento WSDL.

por Israel Aéce

Há algum tempo, eu escrevi um artigo sobre como expor serviços construídos em WCF através do modelo REST, e além disso, foi comentado também sobre as principais diferenças no modelo REST com SOAP, apontando as características de cada uma deles. Um dos detalhes que ficou para trás foi o documento WSDL.

Como sabemos, o WSDL (Web Service Description Language), é um documento baseado em XML, que descreve todas as características (definições) de um determinado serviço, exposto através do modelo SOAP. É justamente esse documento que é utilizado por ferramentas como o svcutil.exe e a opção "Add Service Reference" do Visual Studio, para gerar uma classe que representará o proxy, que por sua vez, será utilizado pelos clientes para consumir o serviço como se fosse uma classe local, mas durante a execução, a mensagem será enviada ao ponto remoto.

Em serviços baseados no modelo REST, não temos essa opção, ou seja, pois o documento/padrão WSDL não suporta endpoints baseados em formato REST. Uma das dificuldades que isso causa é a não possibilidade de gerar um proxy do lado do cliente para facilitar o consumo deste serviço. Além disso, também iremos nos deparar com a dificuldade em visualizar quais são as operações, parâmetros e eventuais resultados que o serviço expõe para seus clientes.

A finalidade do artigo é abordar como resolveremos o segundo problema, ou seja, a exposição das informações pertinentes à documentação, ou melhor, à descrição do serviço. A primeira opção para expor isso, é utilizando o behavior WebHttpBehavior, que expõe uma propriedade chamada HelpEnabled, que quando definida como True, exibe uma página em formato HTML, com todas as operações que o serviço possui, e com exemplos de como invocar cada uma delas. Abaixo temos o código (declarativo) necessário para habilitar este recurso, e em seguida, temos a imagem que corresponde a página gerada automaticamente:

<?xml version="1.0"?>
<configuration>
<system.serviceModel>
<services>
<service name="Service">
<endpoint
address=""
binding="webHttpBinding"
contract="IService"
endpointConfiguration="edpConfig" />
</service>
</services>
<behaviors>
<endpointBehaviors>
<behavior name="edpConfig">
<webHttp helpEnabled="true"/>
</behavior>
</endpointBehaviors>
</behaviors>
</system.serviceModel>
</configuration>

A outra possibilidade que temos é utilizando um novo recurso, que é disponibilizado a partir do WCF-REST Starter Kit, que é conhecido como Automatic Help Page. Tudo o que precisamos fazer aqui é a mudar a factory responsável por criar os hosts que gerenciam a execução do serviço. Depois de instalar o WCF-REST Starter Kit, precisamos referenciar o assembly Microsoft.ServiceModel.Web.dll, que fornecerá uma classe chamada WebServiceHost2Factory, e devemos utilizá-la no arquivo *.svc, como é mostrado abaixo:

<%@ ServiceHost
Language="C#"
Debug="true"
Service="Service"
Factory="Microsoft.ServiceModel.Web.WebServiceHost2Factory"
CodeBehind="~/App_Code/Service.cs" %>

Com essa funcionalidade habilitada, podemos acessar a página que irá descrever o serviço, acrescentando à URL do serviço a string "/help", como podemos notar na imagem abaixo. Note que passamos a ter a descrição do mensagem de requisição e resposta, e além disso, podemos acrescentar mensagens customizadas nas nossas operações, utilizando o atributo WebHelpAttribute, que automaticamente aparecerá nesta mesma página, fornecendo ainda mais informações para facilitar a vida de quem consumirá a respectiva operação.

Conclusão: Apesar dos recursos que vimos neste artigo, isso ainda não é capaz de facilitar a vida de quem o consome, já que ainda será necessário a criação das requisições e o tratamento das respostas de forma bastante manual. Há ainda alguns novos recursos, também fornecidos pelo WCF-REST Starter Kit, quais você pode combinar com essa documentação, e tornar o consumo mais simples.