Import WSDL

Esta funcionalidade permite que serviços expostos por meio do protocolo SOAP e descritos em documentos WSDL sejam convertidos parcialmente em APIs REST. O usuário poderá então usar a API cadastrada para chamar os serviços e operações expostos em SOAP de maneira mais direta e usando formatos ditados na arquitetura REST.

Quando o API Manager lê o arquivo WSDL importado, todos os Ports e Operations do arquivo são transformados em Resources e Operations de uma API REST.

Arquitetura

Internamente, o fluxo de execução de uma requisição a um serviço WSDL ocorre da seguinte forma:

Vamos considerar para os exemplos abaixo a utilização de uma API com uma operação chamada /convertweight, vinda do WSDL http://www.webservicex.net/ConvertWeight.asmx?WSDL).
wsdl call arch

A imagem acima representa o que acontece no gateway durante uma chamada. Primeiramente, os dados no corpo da requisição são transformados de JSON para XML. Em seguida, o interceptor XSL Transformation realiza a transformação via mapeamento dos dados XML do corpo com o XSL presente dentro do próprio interceptor para a criação de um envelope SOAP válido para ser usado posteriormente em uma chamada HTTP POST comum, como demonstrado na imagem abaixo.

wsdl call back

Depois que o servidor SOAP retorna a resposta da execução da chamada POST, a resposta desta chamada retorna para o Gateway para sofrer outra transformação. O envelope SOAP com o resultado da operação passa novamente por um interceptor XSL Transformation, que tem a função de transformar o conteúdo do envelope SOAP em um JSON usando o mapeamento presente em um documento XSL salvo dentro do interceptor. Terminada essa transformação, o Gateway retorna um corpo JSON para o cliente.

Importando um WSDL

O cadastro de uma API para uso do WSDL é muito semelhante ao cadastro de uma API comum. Para começar, clique no botão Import WSDL dentro da seção Resources da API (seja quando estiver criando uma nova API ou editando uma já existente).

wsdl import button

Uma janela modal será aberta, por meio da qual você poderá importar o arquivo WSDL de duas formas: via inserção da URL onde o WSDL está hospedado,

wsdl import url modal

ou via upload do arquivo com extensão .wsdl ou .xml:

wsdl import file modal

Depois da escolha do método de upload do seu arquivo WSDL, clique no botão Validate. O conteúdo do arquivo só será mandada para o servidor se os dados do arquivo ou URL inseridos estiverem corretos.

O botão Validate irá retornar mensagens de erro caso o arquivo ou URL carregados sejam inválidos. No caso de falha na leitura do WSDL de uma URL, a seguinte mensagem será exibida:

wsdl invalid url

Nesse caso, a URL foi passada com formato correto, mas a leitura do WSDL presente nessa URL apresentou falha, pois o arquivo tem algum conteúdo inválido em sua integridade.

Por sua vez, se o formato de URL for inválido (só são aceitas URLs iniciadas por http(s)://), a seguinte mensagem será exibida:

wsdl invalid url format

Caso o formato não seja aceito, o botão Validade não será habilitado.

Se a URL estiver correta e o arquivo do WSDL tiver conteúdo válido, o botão de upload será habilitado e, por meio dele, será possível enviar os dados para o servidor.

wsdl valid url content

Se a importação do WSDL ocorrer por meio de arquivos, a validação é apresentada da seguinte maneira: se você tentar validar um arquivo de extensão inválida, a mensagem "Invalid WSDL Format" aparecerá, indicando que o formato do arquivo carregado não é aceito pela aplicação (só arquivos nos formatos .wsdl e .xml são aceitos).

wsdl invalid file format

Se o arquivo tiver formato válido mas conteúdo com problemas, a mensagem de erro de validação será a seguinte:

wsdl invalid file load

No caso acima, a validação do arquivo acusa que o conteúdo do WSDL é inválido, causando algum tipo de erro no envio do arquivo.

Se o arquivo escolhido tiver a extensão correta e um conteúdo íntegro, o botão Validade retornará uma mensagem de sucesso e o botão Upload será habilitado.

wsdl valid file upload

Após o upload, o usuário será direcionado para a tela de listagem dos serviços e operações presentes no WSDL. (No exemplo mostrado abaixo, usamos o WSDL do web service dos Correios para rastreamento de objetos: http://webservice.correios.com.br/service/rastro/Rastro.wsdl.)

wsdl listing

A tela apresenta cada serviço descrito no WSDL (no caso, o ServicePortBinding) com o seu conjunto de operações (buscaEventosLista e buscaEventos).

Ao expandir um serviço do WSDL, temos a lista das seguintes informações:

  • WSDL Operation: representa a operação presente dentro do WSDL e disponível no serviço SOAP exposto.

  • Description: descrição (não obrigatória) do que a operação realiza.

  • REST Method: utilizado para a criação do recurso REST, representa o método pelo qual o recurso da API será cadastrado. O método padrão é sempre POST, pois é aceito pelos serviços do tipo SOAP. Para outros casos, talvez seja necessário criar transformações via interceptores para a conversão do método.

  • REST Operation: representa a operação REST na qual aquele elemento irá se transformar.

Para transformar cada uma das operações em recursos da sua API, selecione os itens desejados, defina o método HTTP que cada um irá representar e altere o nome de cada recurso, caso necessário.

Depois de completar tudo, clique no botão Save and return to Resources. Você será redirecionado para a tela de listagem de recursos com os itens já transformados:

wsdl selecting operations

Após essa etapa, você pode continuar com o fluxo normal de criação da API.

Caso seja necessário incluir ou editar algum recurso criado a partir de um WSDL, o arquivo deve ser importado novamente, e todos os recursos já cadastrados que fizerem parte daquele WSDL virão marcados na exibição das operações.

A URL de destino de seus novos recursos de API REST será o endpoint do serviço WSDL.

Depois de realizar a importação de um arquivo WSDL e estabelecimento dos recursos relacionados, haverá a inclusão de seis interceptores que irão auxiliar na chamada e execução de cada operação gerada a partir do WSDL (para saber mais sobre interceptores, clique aqui). Eles são:

Fluxo de Requisição

1 XSL Transformation

Este interceptor contém, em seu interior, um arquivo no formato XSL para transformações no gateway.

2 Header

O primeiro interceptor de Header indica o Content-Type usado para tráfego de informações de entrada no gateway (text/xml). O segundo interceptor indica o valor do SOAPAction da operação que será executada. Caso o serviço não tenha SOAPAction atribuído, este último interceptor não será criado.

1 HTTP Method

Realizado para a conversão do método chamado para POST, seguindo o padrão SOAP.

Fluxo de Resposta

1 XSL Transformation

Contém o arquivo XSL responsável pela transformação da resposta da chamada para o formato JSON, seguindo os mapeamentos presentes no arquivo.

1 Header

Este interceptor indica o Content-Type usado na resposta do servidor (application/json).

wsdl interceptors

A imagem acima mostra a aplicação dos interceptors no recurso /buscaeventos. Esses interceptores serão usados pelo gateway para execução das chamadas a essa ou outras operações criadas.

If necessary, all present interceptors can be edited, and new interceptors can be added to assist in the execution of the processes.
Thanks for your feedback!
EDIT

Share your suggestions with us!
Click here and then [+ Submit idea]