Você recebe um novo projeto e em uma das etapas é necessário realizar a integração do seu sistema via Web Services com outra empresa e vice-versa. Duas empresas de TI que podem inclusive possuir produtos concorrentes, mas que necessitam trabalhar em conjunto para atender o cliente em comum.
Aparentemente a primeira coisa a ser feita é ligar para a empresa em questão e solicitar os arquivos pdf que contenham exemplos de chamadas ao Web Services deles, certo? Ou talvez o nosso cliente já tenha conseguido esses documentos na versão 1.00 e tenhamos que mandar alguns e-mails para verificar se o documento está atualizado? Também temos que atualizar a nossa documentação para refletir as últimas modificações que a equipe realizou, correto?
Bom, se o parágrafo acima parece familiar, saiba que isso deveria ser bem mais simples. A única pergunta a ser feita para ambas as empresas é “Qual a URL do seu WSDL?”
WSDL, que significa Web Services Description Language, é um padrão de mercado para descrever Web Services de forma a eliminar ao máximo a necessidade de comunicação entre as partes envolvidas em uma integração de dados. Ele normalmente é encontrado quando acrescentarmos “?wsdl” ao final da URL onde o Web Service está hospedado.
Observe a Listagem 1 onde temos um WSDL como exemplo.
Listagem 1. Exemplo de um arquivo WSDL.
<wsdl:definitions xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
xmlns:tns="http://www.mayconoliveira.org/webservices/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" name="webservices"
targetNamespace="http://www.mayconoliveira.org/webservices/">
<wsdl:documentation>Prezado fornecedor, este é um Web Service de
exemplo, voltado a inclusao de clientes.
</wsdl:documentation>
<wsdl:types>
<xsd:schema targetNamespace="http://www.mayconoliveira.org/webservices/">
<xsd:element name="ClienteRequest">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="nome" type="xsd:string">
<xsd:annotation>
<xsd:documentation>
Aqui você deve enviar o nome do cliente
exatamente como consta em seu RG
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="idade" type="xsd:int" minOccurs="0">
<xsd:annotation>
<xsd:documentation>
Informe a idade do cliente a ser utilizado no
email marketing.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ClienteResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="mensagem" type="xsd:string">
<xsd:annotation>
<xsd:documentation>
Mensagem devolvida do Web Service.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="numeroRecibo" type="xsd:int"
minOccurs="0">
<xsd:annotation>
<xsd:documentation>
Recibo da inclusão. Somente é devolvido em
caso de sucesso.
</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</wsdl:types>
<wsdl:message name="ClienteRequest">
<wsdl:part element="tns:ClienteRequest" name="parameters" />
</wsdl:message>
<wsdl:message name="ClienteResponse">
<wsdl:part element="tns:ClienteResponse" name="parameters" />
</wsdl:message>
<wsdl:portType name="webservicesPortType">
<wsdl:operation name="incluirCliente">
<wsdl:input message="tns:ClienteRequest" />
<wsdl:output message="tns:ClienteResponse" />
</wsdl:operation>
</wsdl:portType>
<wsdl:binding name="webservicesSOAP" type="tns:webservicesPortType">
<soap:binding
transport="http://schemas.xmlsoap.org/soap/http" />
<wsdl:operation name="incluirCliente">
<soap:operation soapAction=
"http://www.mayconoliveira.org/webservices/incluirCliente" />
<wsdl:input>
<soap:body use="literal" />
</wsdl:input>
<wsdl:output>
<soap:body use="literal" />
</wsdl:output>
</wsdl:operation>
</wsdl:binding>
<wsdl:service name="webservices">
<wsdl:port binding="tns:webservicesSOAP" name="webservicesSOAP">
<soap:address location="http://www.mayconoliveira.org/meuwebserviceaqui" />
</wsdl:port>
</wsdl:service>
</wsdl:definitions>
O WSDL da Listagem 1 é um descritor de um WebService simples que recebe o nome e a idade de um cliente e retorna um número de recibo em caso de sucesso. Mas essa explicação já foi possível de extrair ao ler o documento, correto? A tag documentation nos possibilita a inclusão da nossa documentação, dispensando um documento auxiliar como um pdf para explicar os objetivos do Web Service ou para que serve cada campo. Isso não só garante que a informação fique centralizada, como também facilita a leitura por terceiros.
Também podemos extrair deste WSDL a informação que a idade do cliente a ser enviada pelo invocador do serviço e o número do recibo devolvido pelo servidor são opcionais, ou seja, podem não ser informados. Isso pode ser verificado através do atributo minOccurs com o valor 0 (O default, caso não informado, é 1, ou seja, obrigatório). Sabemos também que idade é tipo “int” (inteiro) e o nome é do tipo string. Para maiores informações sobre todos os tipos de dados, verifique a documentação oficial em http://www.w3.org/TR/xmlschema-2/#datatype.
Existem outras informações que podemos verificar, tais como o endereço real a qual o Web Service está hospedado (tag address), valores que temos que informar no Header da requisição HTTP, tais como a SOAPAction disponível na tag soapAction, entre outras. Todas elas juntas servem para gerar uma requisição HTTP válida ao servidor destino, como na Listagem 2.
Listagem 2. Requisição http gerada a partir do WSDL da Listagem 1
POST http://www.mayconoliveira.org/ HTTP/1.1
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://www.mayconoliveira.org/webservices/incluirCliente"
Content-Length: 332
Host: www.mayconoliveira.org
Connection: Keep-Alive
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://www.maycon.org/webservices/">
<soapenv:Header/>
<soapenv:Body>
<web:ClienteRequest>
<nome>Maycon Fabio de Oliveira</nome>
<idade>27</idade>
</web:ClienteRequest>
</soapenv:Body>
</soapenv:Envelope>
Agora, observe o WSDL da Listagem 3(Uma parte está omitida para facilitar visualização).
Listagem 3. Exemplo de um arquivo WSDL de difícil compreensão .
<wsdl:definitions>
...
<wsdl:types>
<xsd:schema targetNamespace="http://www.mayconoliveira.org/webservices2/">
<xsd:element name="ClienteRequest">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="in" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
<xsd:element name="ClienteResponse">
<xsd:complexType>
<xsd:sequence>
<xsd:element name="out" type="xsd:string" />
</xsd:sequence>
</xsd:complexType>
</xsd:element>
</xsd:schema>
</wsdl:types>
...
</wsdl:definitions>
Com um WSDL como o da Listagem 3, o que conseguimos saber? Não muita coisa. Sabemos que existe uma operação no Web Service em que o nome da primeira tag após a tag raiz (ClienteRequest) se chama “in” para o envio e “out” para o retorno. Mas o que devemos informar nessas tags? Valores separados por vírgula? Outro XML? Ambas as opções representam uma má prática, pois novamente estamos escondendo a informação dos interessados. A requisição HTTP mais próxima que podemos montar sem ter que entrar em contato com a empresa é algo como a Listagem 4.
Listagem 4. Requisição HTTP gerada a partir do WSDL da Listagem 3
POST http://www.mayconoliveira.org/ HTTP/1.1
Content-Type: text/xml;charset=UTF-8
SOAPAction: "http://www.mayconoliveira.org/webservices2/incluirCliente"
Content-Length: 287
Host: http://www.mayconoliveira.org
Connection: Keep-Alive
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:web="http://www.mayconoliveira.org/webservices2/">
<soapenv:Header/>
<soapenv:Body>
<web:ClienteRequest>
<in> O QUE DEVEMOS INFORMAR AQUI? </in>
</web:ClienteRequest>
</soapenv:Body>
</soapenv:Envelope>
Apesar de todas as vantagens do uso adequado do WSDL, o mesmo é normalmente negligenciado pelas empresas de TI devido a sua complexidade. Ao invés disto, utilizam-se do que se chama de abordagem de desenvolvimento bottom-up, a qual você escreve o seu Web Service utilizando sua linguagem de programação favorita e a mesma gera o documento WSDL para você. A princípio, isso parece ser muito bom, mas em longo prazo, isso pode gerar problemas como:
- Em uma migração de tecnologia (linguagem de programação, troca de servidor de aplicação), pode ser que o novo Web Service, criado para substituir o anterior, não aceite a requisição que está sendo enviada pelos programas clientes, que pode vir a parar de funcionar.
- Cada linguagem de programação ou ferramenta vai gerar um documento WSDL diferente.
- Dependendo da linguagem de programação ou da ferramenta utilizada, pode ser que sejam gerados tipos de dados não suportados oficialmente pela W3C (Órgão “regulamentador” do padrão WSDL, SOAP e XML).
E para aqueles que acreditam não precisar mais se preocupar com esse tipo de integração porque Web Service do tipo SOAP não é mais utilizado desde o surgimento do REST (outro tipo de Web Service), fica a informação de que hoje temos muitos projetos contemplando Web Services do tipo SOAP, tais como Nota fiscal eletrônica e TISS (Troca de informações na Saúde Suplementar da ANS).
Mas, como tudo na informática, nem tudo é como deveria ser. Em diversas ocasiões, mesmo com o endereço de um WSDL, passamos por situações em que a requisição que deve ser montada não chega nem perto do que o mesmo especifica. Neste caso, somente o contato com o fornecedor resolve. Claro que neste momento estaremos munidos da informação de que o fornecedor está fazendo errado e que cada segundo do nosso tempo gasto com informações inválidas estará correndo por conta do mesmo. O WSDL é o contrato do serviço, ou seja, ele é a regra!
Neste artigo, vimos a importância que o documento WSDL tem em uma integração de dados entre duas organizações. Ele é um documento complexo e com muitas funcionalidades, que se bem utilizadas, podem facilitar muito a utilização e a reutilização de Web Services. Certamente vale se aprofundar no assunto.
