Criando APIs com OutSystems

O que é API? 

O termo API, refere-se à sigla em inglês Application Programming Interface ou em português Interface de Programação de Aplicações, faz referência a uma interface de aplicações, que pode comunicar-se com outros sistemas. 

O conceito de API, diferente das funções que os códigos desempenham, tem objetivo de fazer uma comunicação entre softwares, sem a necessidade de alterar, complementar ou entender algo no outro sistema. 

Imagine que um sistema de vendas realize suas funções de venda, controle de estoque, emissão de notas. Após um período de utilização, torne-se extremamente necessário que ao realizar uma venda à prazo, seja necessário consultar as restrições do comprador no ato da compra. Ao invés de desenvolver toda a busca e lógica de restrição de uma pessoa física dentro do sistema de vendas, com suas regras, fluxos e validações, basta consumir uma API de um sistema específico de consulta de restrições e integra-lo no sistema de vendas, sem saber como ele realiza as consultas. 

Sendo assim, API trata-se de um conjunto de rotinas e padrões estabelecidos, e documentados por uma aplicação, para que outras aplicações consigam utilizar suas funcionalidades, sem precisar conhecer detalhes da implementação. Desta forma, entende-se que as APIs permitem uma interoperabilidade entre aplicações. Em outras palavras, a comunicação entre aplicações e entre os usuários. 

O que são protocolos de API 

Agora que você já sabe que as APIs oferecem uma interface de comunicação entre a sua aplicação e a de outra pessoa, deve estar se perguntando como estes canais mantêm padrões constantes na hora de oferecer estes serviços. 

O uso de APIs está condicionado a procedimentos e convenções padrão, os chamados protocolos de API. Estes protocolos estabelecem regras para a comunicação com APIs, garantindo a estabilidade e a eficiência da troca de solicitações e respostas. 

Cada API opera de acordo com um protocolo específico, a depender de suas necessidades e objetivos. 

Os dois protocolos mais comuns de API são: 

REST 

Um dos protocolos mais populares para o desenvolvimento de APIs, REST é uma sigla para Representational State Transfer (Transferência de Estado Representacional). APIs e aplicações de arquitetura REST são denominados serviços RESTful. 

Este estilo de arquitetura emprega uma dinâmica cliente/servidor sem estado (stateless), que separa o front-end do back-end da API e oferece mais agilidade e flexibilidade na implementação. 

Apesar do protocolo cliente/servidor sem estado, que não armazena dados entre uma solicitação e outra, as APIs RESTful conseguem armazenar dados em cache para APIs lentas. Para isso, entretanto, a solicitação deve expressar uma permissão de armazenamento em cache. 

SOAP 

O protocolo SOAP também recebe seu nome de um acrônimo: Simples Object Acess Protocol (em português, Protocolo Simples de Acesso a Objetos). Esta tecnologia é uma das mais populares para a criação de APIs Web. 

APIs SOAP são conhecidas por sua extensibilidade e independência de estilos de programação específicos. Além disso, este é um protocolo dito neutro, isto é, ele pode operar por diferentes protocolos de comunicação, como HTTP, SMTP, TCP e outros. Estas características facilitam a adição de funcionalidades ao código. 

O protocolo visa mediar trocas de informações estruturadas de maneira descentralizada. Apesar de amplamente utilizado, o Protocolo Simples de Acesso a Objetos tem regras e procedimentos bastante rígidos, que requerem atenção especial do programador. 

Métodos de uso de API: 

• Get (Data query/search) 

Este método permite que informações/dados sejam pesquisadas de acordo com o recurso e o ponto final inseridos. Você também pode (e deve) usar este método em conjunto com filtros de recursos e paging. Através deste método, o backend retornará as informações consultadas. 

• Post (Data sending/loading) 

Criar/executar uma carga de novas informações para a base. É necessário enviar as informações no padrão JSON exigido no órgão de solicitação. 

• Put (Atualização de dados) 

É usado para atualizar ou editar as informações já existentes na base. O uso do Put é amplamente conhecido e o responsável por alterar/atualizar as informações existentes. 

• Delete (Excluir dados) 

Como o nome indica, é o método responsável pela eliminação das informações. Este é um ponto importante que só é incluído dentro da API se, para a regra comercial, for necessária uma exclusão de informações da base (e se ela for permitida). Algumas empresas não permitem este uso, pois é uma ação que apagará definitivamente o registo em particular. 

API Em OutSystems 

OutSystems simplifica a tarefa de consumir e expor funcionalidades como APIs REST padrão ou serviços web SOAP sem qualquer codificação manual. Cenários de integração empresarial mais complexos que exigem o uso de MQSeries, TIBCO, BizTalk e outros ESBs de middleware também são suportados por serviços da web. 

REST 

Determinada a tornar a integração com APIs REST o mais simples possível, a OutSystems introduziu uma forma totalmente nova de automatizar o consumo de uma API REST. 

Não há contrato nas APIs REST, apenas um conjunto de exemplos geralmente presentes na documentação do provedor. Em vez de lutar contra esse fato, nós o abraçamos. Basta digitar o endereço para a API REST e usar os exemplos JSON para permitir que OutSystems descubra automaticamente a estrutura subjacente presente. Em seguida, ele cria uma interface que pode ser arrastada na lógica visual como se fosse qualquer outra parte da lógica de negócios ou serviço da web. Os usuários só precisam preencher os parâmetros e começar a usar a API. 

A OutSystems cria toda a estrutura necessária para suportar a análise de impacto e mudança em toda a app. Se a API mudar, tudo é atualizado, corrigido automaticamente e verificado quanto ao impacto. 

Para expor serviços REST, defina a API REST com a linguagem visual OutSystems e clique para publicar. O resultado é uma API REST baseada em JSON simples, rápida e segura. 

SOAP 

O consumo de serviços da Web SOAP envolve fornecer a URL exatamente da mesma maneira que seria digitada em um navegador da Web. OutSystems irá buscar o WSDL e criar todas as estruturas de dados necessárias para que os métodos de serviço web sejam usados ​​visualmente. 

A exposição de serviços da web SOAP é feita expondo os métodos. OutSystems irá criar automaticamente o WSDL e URL que podem ser consumidos por outras aplicações. 

Em ambos os casos, a análise de XML é evitada. 

Se você deseja expor métodos para permitir que outros sistemas recuperem ou manipulem informações, você pode fazer isso usando uma API REST. 

Crie o serviço da API REST 

1. Na guia Lógica, abra a pasta Integrações. 
2. Clique com o botão direito do mouse em REST e selecione Expor API REST.... 
3. Defina o nome de sua API REST. Exemplo: Lista telefônica. 

Crie o método da API REST 

1. Clique com o botão direito do mouse em sua API REST e escolha Adicionar método de API REST. 
2. Defina o nome do seu método de API REST. Exemplos: GetContacts, CreateContact, UpdateContact. 
3. Certifique-se de que a propriedade HTTP Method esteja definida como o verbo HTTP correspondente à ação que seu método executará: 

• GET - Leia 
• POST - Criar 
• PUT - Atualizar 
• Delete - Apagar 

1. Projete o método como uma ação que recupera ou manipula os dados que você está expondo. Exemplos: GetContacts retornará a lista de todos os contatos, CreateContact ou UpdateContact receberá um registro de contato e retornará o Id do contato criado ou atualizado. 

Depois de implantar o aplicativo, seus endpoints da API REST estarão acessíveis. 

Os endpoints padrão são baseados no método HTTP (GET, POST, PUT, DELETE) e no nome dos métodos REST API. 

Pode testar o seu REST API Method utilizando várias ferramentas disponíveis, como o Postman, ou construindo uma aplicação OutSystems para o efeito. 

Para métodos de manipulação em que o parâmetro de entrada é um registo (como POST ou PUT), você terá que adicionar o cabeçalho Content-Type à solicitação, com o valor application/json. 

Fluxo do método da API REST 

Quando é recebido um pedido ao seu Método API REST, a OutSystems executa o seguinte fluxo: 

1. Validações de Segurança: Depois de receber o pedido do REST API Method, a OutSystems executa as validações de segurança de acordo com as configurações nas propriedades REST API HTTP Security and Internal Access Only. 
2. OnRequest(): o callback OnRequest permite que você execute a lógica sobre as solicitações após recebê-las. 
3. OnAuthentication(): o retorno de chamada OnAuthentication permite adicionar autenticação básica ou autenticação personalizada às solicitações. 
4. Desserialização e Validação de Parâmetros: Desserialização dos parâmetros de entrada e validação dos tipos de dados, valores obrigatórios, etc. 
5. Execute Method: Executa a ação que implementa o REST API Method. 
6. Serialização de Parâmetros: Serialização dos parâmetros de saída para retornar na resposta. 
7. OnResponse(): o retorno de chamada OnResponse permite que você execute a lógica sobre as respostas antes de enviá-las. É sempre executado, mesmo em situação de erro. 

Consumir um serviço Web SOAP 

A OutSystems fornece suporte extensivo para consumir SOAP Web Services com WSDL 1.1 e SOAP 1.1. 

Para consumir um SOAP Web Service em seu aplicativo, faça o seguinte: 

1. Na guia Lógica, abra a pasta Integrações. 
2. Clique com o botão direito do mouse no elemento SOAP e selecione Consumir SOAP Web Service...: 

1. Na caixa de diálogo exibida, especifique o endereço URL onde a definição de serviço da Web (WSDL) pode ser encontrada: 

1. Você deve fornecer o endereço URL exatamente da mesma forma que o digitaria em seu navegador da Web. 
2. Como alternativa, você pode importar um WSDL de seu sistema de arquivos, especificando file:///<filesystem path to wsdl>. 

Quando consome um SOAP Web Service, a OutSystems faz o seguinte por si: 

1. Cria o Serviço Web SOAP. 
2. Cria os métodos de serviço da Web expostos com os parâmetros de entrada e saída correspondentes. 
3. Cria as estruturas para manter os tipos complexos definidos no WSDL. 
4. Mapeia os tipos de dados XML em tipos de dados OutSystems . 

Você pode alterar o nome de SOAP Web Services, Web Service Methods, Parâmetros e Estruturas em seu módulo. 

A OutSystems não fornece suporte direto para Web Services Enhancements (WSE). Em vez disso, você pode usar a API EnhancedWebReferences para implementar a lógica que suporta a funcionalidade fornecida pelos Web Services Enhancements em seus aplicativos. 

Use os métodos de serviço da Web SOAP em seu aplicativo 

OutSystems traduz os métodos expostos por um SOAP Web Service em ações OutSystems, com a mesma semântica de qualquer ação criada por você no Service Studio. 

Agora você pode usar o método recém-criado em seu aplicativo da mesma forma que usa as ações de servidor restantes: 

1. Vá para o fluxo de ação no qual deseja usar o método de serviço da Web. 
2. Na guia Lógica, abra a pasta Integrações e o elemento SOAP. 
3. Abra o SOAP Web Service e arraste o Web Service Method para o seu fluxo de ação. 

Autor: Thiago Mari – OutSystems Expert