Swagger na WEB API

A partir da versão 2 da Web API, o Swagger apresenta-se como a ferramenta de documentação e invocação dos métodos da Web API, passando a ser a página de apresentação.

Módulos e versões

Uma vez que a Web API disponibiliza praticamente todos os métodos da API do ERP, e para garantir elevados índices de performance na apresentação da interface para chamar os métodos, a interface do Swagger está separada por módulo/versão da Web API.

Assim, na combobox do topo da página é possível escolher o módulo e a respetiva versão a explorar (clicando no botão Explore):

Controllers e Métodos

Tal como abordado no artigo relativo às características da Web API, os controllers representam cada uma das entidades de negócio do módulo selecionado. Já os métodos correspondem aos serviços disponibilizados pela entidade de negócio.

Com o Swagger, é possível obter a informação detalhada sobre cada entidade e os respetivos serviços, bastando clicar nos itens pretendidos.  De seguida, poderá consultar um exemplo de edição dos tipos de documentos de venda:

Além da rota do pedido - HTTP Request (GET) e respetiva descrição -, é apresentado o HTTP Response Code do pedido (200 - OK), o formato base da resposta e os parâmetros para a invocação (com a respetiva descrição).

O botão Try it out! permite, após a autenticação, a inovação do serviço selecionado.

Pedido de Token

Em cada entidade de negócio, é apresentado o método Login que permite obter um token (chave) para a autenticação em formato Bearer (também denominada de autenticação via token):

No pedido do token, um parâmetro apresenta especial relevo num contexto de utilização dos motores Primavera em contexto web. O sessionkey deve representar uma chave única que disponibilizará um contexto de integração independente e isolado dos demais pedidos.

A invocação deste serviço retorna uma chave com o seguinte formato:

O tempo definido para a expiração do token (expired_in) pode ser alterado no ficheiro Web.config, no setting TokenExpirationMinutes:

A string que é apresentada no item “access_token” da resposta corresponde à chave a utilizar nos pedidos. Para tal, deverá passar essa string para o campo presente no topo da página, com o prefixo Bearer:

Invocação de um Pedido

Após a autenticação e inserção da token recebido no campo Header Authorization, é possível invocar qualquer serviço disponível.

Assim, tendo como exemplo a edição de um tipo de documento de venda, a invocação pode ser efetuada após definir os respetivos parâmetros:

Renovação de token

Quando o token expira, é retornado um erro 401 – Unauthorized com a mensagem “Authorization has been denied for this request.”. Neste cenário, deverá realizar um novo pedido token, utilizando o mesmo método do primeiro pedido (/token).

Para que a renovação de token reutilize o mesmo contexto de integração, garantindo a otimização dos recursos e maior celeridade na resposta, deverá indicar no header do pedido de novo token, o token anterior, entretanto expirado (header Authorization).

Logout

Está disponível um endpoint de logout que permite libertar recursos de um determinado contexto de utilização.

O método é invocado sem parâmetros, mas implica a identificação do token respetivo no header do pedido (header Authorization).

Este método permite libertar memória do processo do IIS, bem como remover sessões sleeping da base de dados.