Utilizando API REST
- Henrique Schrock Piana (Unlicensed)
- Eduardo Barbuda Rodrigues
- Leonardo Gama
Veja antes:
Documentação Swagger - webPosto - Confluence (atlassian.net)
Obter Chave de Integração - webPosto - Confluence (atlassian.net)
Conceito API REST
API REST, também conhecida como API RESTful, é uma API (Interface de Programação de Aplicações) em conformidade com as restrições do estilo de arquitetura REST, permitindo a interação com serviços web RESTful. REST é a sigla em inglês para "Representational State Transfer", que em português significa "transferência de estado representacional".
API é um conjunto de definições e protocolos usado no desenvolvimento e na integração de aplicações. Às vezes, APIs são descritas como um contrato entre um provedor e um usuário de informações, estabelecendo o conteúdo exigido pelo consumidor (a chamada) e o conteúdo exigido pelo produtor (a resposta).
REST não é um protocolo ou padrão, mas sim um conjunto de restrições de arquitetura. Os desenvolvedores de API podem implementar a arquitetura REST de maneiras variadas.
Pense nas APIs como um mediador entre os usuários ou clientes e os recursos ou serviços web que eles querem obter. As APIs também servem para que organizações compartilhem recursos e informações e, ao mesmo tempo, mantenham a segurança, o controle e a obrigatoriedade de autenticação por permitirem determinar quem tem acesso e o que pode ser acessado
Uma requisição consiste em:
Um verbo ou método HTTP, que define que tipo de operação o servidor vai realizar;
Um header, com o cabeçalho da requisição que passa informações sobre a requisição;
Um path (caminho ou rota) para o servidor.
Informação no corpo da requisição, sendo esta informação opcional.
Métodos HTTP:
O método GET (Consulta) é o método mais comum, geralmente é usado para solicitar que um servidor envie um recurso;
O método POST (Cadastro) foi projetado para enviar dados de entrada para o servidor. Na prática, é frequentemente usado para suportar formulários HTML;
O método PUT (Alteração) edita e atualiza todos os atuais dados do recurso de destino pelos dados passados na requisição;
O método Patch (Alteração) aplica modificações parciais em um recurso. Logo, é possível modificar apenas uma parte do recurso. Diferente do método PUT.
O método DELETE (Exclusão) que como o próprio nome já diz, deleta certo dado ou coleção do servidor.
Código de retorno:
200 (OK), requisição atendida com sucesso;
201 (CREATED), objeto ou recurso criado com sucesso;
204 (NO CONTENT), objeto ou recurso deletado com sucesso;
400 (BAD REQUEST), ocorreu algum erro na requisição (podem existir inumeras causas);
404 (NOT FOUND), rota ou coleção não encontrada;
500 (INTERNAL SERVER ERROR), ocorreu algum erro no servidor.
Repositório com todos endpoints do webPosto:
Explicação: Documentação Swagger
Utilizando o Postman para obter dados dos Endpoints
Link para download do Postman: https://www.postman.com/downloads/
Faça o download/instalação do programada postman. (Ao iniciar o programa ele solicita para criar login, é opcional esse login).
O Postman é uma ferramenta que dá suporte à documentação das requisições feitas pela API. Ele possui ambiente para a documentação, execução de testes de APIs e requisições em geral.
Todos os endpoint do webPosto, utilizam como parâmetro o campo CHAVE=sad54a64sda4s6d46a4s6d46a4sd. Como obter essa chave
Criando Request
A criação das request serve para iniciar a integração com a API, utilizando os métodos (GET, POST, PUT, PATCH, DELETE). Podem ser criadas de duas formas, 1 criando uma request avulsa, 2 importando a collection informada no final desse manual.
1- Criando request avulsa:
Na tela inicial do postman, clicar em New.
Na segunda tela que abrir clicar em HTTP.
A próxima etapa é definir qual método HTTP utilizar:
De exemplo vamos utilizar o método GET, selecione-o.
Lembrando que o método depende do endpoint que vai ser escolhido. Cada endpoint de uma API tem seu método próprio.
Para saber qual método dos endpoints do webPosto:
Após selecionar o método GET, vamos definir a URL base e depois o endpoint que vamos utilizar.
Essa URL é a base da integração com o endpoint que vamos escolher. Então toda comunicação com uma API é obrigatório ter a URL base.
Para saber qual a URL base dos endpoints do webPosto:
Agora vamos definir qual endpoint vamos utilizar:
De exemplo utilizamos o endpoint
Todo endpoint possui seu parâmetro(filtro) especifico
Em alguns casos o endpoint não possui parâmetro ou filtro para informar. Isso acontece quando o retorno do endpoint não tem muita informação. Como saber quais são os parâmetros que o endpoint precisa: .
Vamos definir os parâmetros:
Após definir os parâmetros, pressione SEND.
SEND significa que estamos fazendo uma requisição no servidor do webPosto, para retornar os dados do endpoint.
Retorno do endpoint.
Atenção para o Status: 200 OK -
O retorno do endpoint de abastecimento possui o mesmo resultado apresentado na tela de Movimentos > Abastecimentos do webPosto, lembrando de utilizar os mesmos filtros(API x webPosto):
2- Importando collection no Postman:
Faça o download da collection que esta no final da pagina.
Para importar a collection no postman, basta arrasta e soltar conforme a imagem:
Outra forma de importar, é clicando na opção Import:
Após a importação abrirá a tela com os endpoints em pastas separadas:
O Postman possui variáveis de ambiente para configurar:
Na collection informada abaixo possui essas variáveis, para facilitar a usabilidade da ferramenta. Para configurar basta clicar no nome da collection criada (Quality_API_GET Copy Teste), para aparecer as configurações da mesma.
Clicar em Variables, assim será listado todas as variáveis criadas. Permite editar, incluir, excluir, para alterar, só clicar em cima do registro que precisa alterar e digitar o que precisa.
Após efetuar alterações basta pressionar CTRL+S para salvar.
Incluir:
Excluir:
A variável CHAVE, precisa ser preenchida com a chave de integração, mencionada no inicio desse manual.
Preencher nos dois campos informado:
Após inserir a chave e pressionar CTRL+S para salvar.
Agora pode entrar em qualquer endpoint, para consultar. Alguns endpoints precisam ser ajustado a data inicial e final, ou algum outro parâmetro especifico do endpoint.
Nas consultas já vem com as variáveis (url, chave), preenchidos com os dados definidos na configuração da collection.
Collection do Postman APIs GET:
Collection do Postman APIs POST/PUT:
Obs.: Para utilizar as duas collections é necessário informar a CHAVE(Token), nas variáveis de acesso. Para obter essa chave, o dono do posto tem que entrar em contato com o setor comercial da Quality para liberar, e em seguida acessar o webPosto(Retaguarda) para copiar a chave.
Para importar as collections no Postman, é preciso criar uma conta gratuita no aplicativo
As collections não possuem todos os endpoints do webPosto, os mais utilizados somente. Pode ser adicionado mais endpoints na collection do postman conforme necessidade.