SOAP

Uma resposta SOAP pode trazer o resultado de uma operação ou uma falha de processamento, sempre dentro da mesma estrutura de XML. Conhecer essa estrutura e o contrato do serviço ajuda a encontrar o resultado e a separar uma recusa de negócio de uma falha.

A mensagem

O SOAP é um protocolo de troca de mensagens estruturadas em XML. Toda mensagem SOAP tem estas partes:

• Envelope: o elemento raiz, que envolve a mensagem inteira e identifica a versão do SOAP pelo namespace.
• Header: o cabeçalho opcional, com informações de controle, como a segurança e a identificação.
• Body: o corpo, com os dados da operação ou, em caso de falha, um elemento Fault.

Uma operação de registro de venda, por exemplo, pode se chamar InserirVenda, e a resposta, InserirVendaResponse, conforme o contrato do serviço. O elemento da operação fica dentro do Body, e os dados da venda ficam dentro do elemento da operação.

O WSDL, o contrato do serviço

O WSDL é o documento XML que descreve o serviço: as operações, as mensagens de entrada e de saída, o endereço e a forma de chamada. Os tipos e os campos de cada mensagem vêm de schemas XML ligados ao WSDL. O WSDL descreve a estrutura, mas não substitui as regras de negócio da documentação, como os códigos de retorno e os limites.

O endereço de um serviço SOAP costuma terminar em .asmx ou .svc, e o mesmo endereço com ?wsdl no fim devolve a descrição do serviço. O próprio WSDL informa o endereço que executa as operações, e esse endereço pode ser diferente do endereço que devolveu a descrição.

As duas versões

O SOAP tem duas versões em uso, a 1.1 e a 1.2, com diferenças no transporte por HTTP:

• SOAP 1.1: o Envelope usa o namespace http://schemas.xmlsoap.org/soap/envelope/, o Content-Type é text/xml, e a operação vai no cabeçalho SOAPAction.
• SOAP 1.2: o Envelope usa o namespace http://www.w3.org/2003/05/soap-envelope, e o Content-Type é application/soap+xml, com a ação como parâmetro opcional.

O namespace do Envelope identifica a versão, e o prefixo, como soap: ou SOAP-ENV:, é só um apelido. Uma chamada na versão errada costuma ser recusada logo na entrada, com o código 415 ou com uma falha de versão, antes de a operação ser executada.

O resultado: retorno normal e Fault

O Fault é o elemento que representa uma falha no processamento da mensagem, com um código e uma descrição. Na versão 1.1, o código e a descrição ficam em faultcode e faultstring. Na versão 1.2, eles ficam em Code e Reason. O detalhe da falha pode trazer uma causa técnica ou uma regra da aplicação, e por isso o Fault não indica, sozinho, uma falha de rede nem um erro puramente técnico.

No SOAP 1.1 sobre HTTP, um Fault acompanha o código 500. No SOAP 1.2, o código é 400 quando a falha é atribuída a quem enviou a mensagem, e 500 nos outros casos. Uma resposta normal, com o código 200, também pode trazer uma recusa em um campo de retorno do Body, como um código de rejeição definido no contrato. O status HTTP, o Fault e os campos de retorno são lidos juntos.

Credenciais e o nome webservice

As credenciais de um serviço SOAP podem ir no Header, pelo padrão WS-Security, com usuário e senha ou com uma assinatura, no transporte, com o certificado do cliente, ou em campos da própria operação, conforme o contrato.

No dia a dia, a palavra webservice também designa APIs HTTP que não usam SOAP. O nome dado ao serviço não informa o estilo, e a estrutura da mensagem confirma o SOAP.