Versão 2 da Web API

A versão 2 da Web API da versão 10 do ERP apresenta algumas alterações significativas relativamente à versão anterior, nomeadamente:

• As respostas passaram a ter uma estrutura única para todos os métodos;
• Utilização de 4 tipos de HTTP Request (GET, POST, PUT, DELETE);
• Bloqueio de pedidos em simultâneo para o mesmo contexto de integração;
• Utilização do Swagger como ferramenta de documentação e invocação dos pedidos.

Endpoints

Todos os endpoints da versão 2 passam a ser complementados com v2 antes da identificação do módulo.

Assim, a estrutura base do URL dos endpoints passa a ser:

http://localhost:2018/WebApi/v2/{modulo}/{entidade}/{servico}/

Retorno dos pedidos

Na versão 2, a resposta a todos os pedidos passa a ter a mesma estrutura:

{

  "Version": "string",

  "StatusCode": 0,

  "ErrorMessage": "string",

  "Results": {}

}

Esta estrutura pretende tirar no imediato complexidade dos http clients que passam a conhecer uma única estrutura de retorno dos pedidos.

Detalhando as propriedades do objeto de retorno:

• Version: Apresenta a versão da Web API invocada;
• StatusCode: Nesta propriedade, será enviado o HTTP Status Code da resposta;
• ErrorMessage: Em caso de erro, apresenta a mensagem respetiva;
• Results: Objeto com o conteúdo do retorno. Este objeto será sempre um dicionário, cuja chave será uma string (que corresponde ao nome da entidade de retorno) e um objecto de retorno.
  • As entidades que, na API do ERP são passadas como ref, são agora retornadas neste objeto;
  • No caso dos métodos de atualização de entidade de negócio, a entidade atualizada é enviada neste objeto, devidamente atualizadas (com o número efetivamente gravado, por exemplo).

HTTP Request de cada pedido

Na versão 2, utilizamos 4 tipos de HTTP Request:

• GET: utilizado nos métodos que retornam dados (genericamente os métodos de Consulta);
• POST: utilizado nos métodos que criam/atualizam entidades de negócio;
• PUT: utilizado nos métodos que atualizam atributos das entidades de negócio (exemplo: ActualizaValorAtributo);
• DELETE: utilizado nos métodos que realizam operações de remoção de entidades de negócio.

Bloqueio de pedidos simultâneos para o mesmo contexto

Está disponível a configuração BlockMultipleRequestsPerContext (true por defeito) no ficheiro web.config que permite bloquear pedidos realizados em simultâneo para o mesmo motor do ERP.

Os motores do ERP são instanciados em função do token solicitado, sendo garantida a correta separação de recursos quando devidamente instrumentado com o session key.

Quando o session key não é utilizado, podem existir erros uma vez que há recursos partilhados que passam a ser utilizados em simultâneo. Deste modo, esta configuração permite evitar tais erros.

Para saber mais informações, sugere-se a consulta da secção Arquitetura da documentação relativa à Web API.

Documentação da Web API com Swagger

A versão 2 disponibiliza ainda, como mecanismo de documentação e invocação da Web API, a ferramenta Swagger.

O endereço predefinido do Swagger será: http://localhost:2018/WebApi/swagger/ui/index

Este passa a ser também a página de entrada da Web API, ao aceder a http://localhost:2018/WebApi.

Saiba mais sobre a utilização do Swagger no artigo de apoio.