O QUE SÃO APIs?

API é um acrônimo para Application Programming Interface, ou, em português, Interface de Programação de Aplicativos.

O intuito de uma API é trocar dados entre sistemas diferentes. Na maior parte das vezes, essas trocas de dados tem como objetivo automatizar processos manuais e/ou permitir a criação de novas funcionalidades. Resumidamente, uma API funciona como uma “ponte” que cria uma conexão entre um requester (solicitante) a um específico banco de dados.

Por meio de APIs, desenvolvedores podem criar novos softwares e aplicativos capazes de se comunicar com outras plataformas. Por exemplo: caso um desenvolvedor queira criar um aplicativo de mobilidade urbana, na área de caronas, ele não precisa desenvolver uma interface de mapas do zero. Basta utilizar a API do Google Maps. Ou ainda, perceba que existe a integração entre apps como o Spotify e o Instagram, que possibilita compartilhar faixas do Spotify nos Stories do Instagram.

Ainda está meio confuso? Veja este outro exemplo, dessa vez mais voltado ao universo das vendas: um software de CRM, como o PipeRun, recebe uma informação sobre um lead que desistiu de uma compra. Portanto, envia a informação deste lead, via API, para uma outra plataforma, como a RD Station, com o intuito de realizar a nutrição do lead para que este volte a comprar o produto/serviço no futuro. Neste caso, acontece uma troca de dados para automatizar um processo que seria manual.

Ou então: toda vez que um lead entra em uma determinada etapa de funil, um SMS poderá será disparado para este lead, automaticamente. Esse disparo automático só é possível graças à comunicação entre a API do PipeRun e a API da empresa de telefonia.

COMO UTILIZAR UMA API?

Para consumir uma API é necessário realizar uma requisição.

A requisição pode ser realizada tendo os seguintes itens na sua estrutura:

• um URL (endpoint)
• um recurso (informação que está sendo acessada)
• parâmetros query string (parâmetros de busca)
• método de requisição (são os famosos "verbos")
• header
• body

A API sempre retornará um Status Code informando a situação da requisição. Se ela foi bem sucedida, se foi bloqueada por questões de segurança, se o endpoint não existe etc.

Na requisição, utiliza-se um URL. O URL nada mais é que o caminho para fazer a requisição. Esse caminho leva a um destino final, que é chamado de endpoint.
 

Base URL
Esse é o início do URL da requisição, aqui você basicamente especificará a informação de domínio que se repete em qualquer requisição. Digamos que você queira utilizar a API do PipeRun, então:

https://api.pipe.run/v1

Resource (ou Path)
O recurso (resource) é o tipo de informação que você quer que a API te retorne. Por exemplo: vamos simular que estamos buscando saber sobre empresas cadastradas na sua conta do PipeRun. Então acrescentamos o seguinte recurso à base URL:

https://api.pipe.run/v1/companies

Query String
Query string são os parâmetros de busca da requisição. Por exemplo: se eu quisesse saber quais são as empresas cadastradas na conta do PipeRun que possuem um nome que comece com "escritório" (para um exemplo onde eu esteja buscando por escritórios de advocacia):

?starts_with=escritorio

e nossa URL ficaria assim: https://api.pipe.run/v1/companies?starts_with=escritorio

Como podem ver acima, por se tratar de parâmetros de busca da URL você usa o (?) e caso queira utilizar mais de um parâmetro você utiliza o (&).

Exemplo de múltiplos parâmetros: https://api.pipe.run/v1/companies?starts_with=escritorio&id=12345

O método
O método te ajuda a informar o tipo de ação que você está fazendo naquela requisição.
Dentre os principais métodos, temos:

• GET (Buscar dados);
• POST (Enviar dados);
• PUT e PATCH (Atualizar dados);
• DELETE (Deletar dados).

Headers
Headers ou cabeçalhos da requisição permitem que você envie informações adicionais na requisição. Ele pode ser utilizado para inúmeras funções, como: autenticação, formatação de objeto, etc.

No caso da API do PipeRun, é necessário utilizar o token da conta para autenticação, ao realizar as requisições. Caso não seja utilizado, a API não permitirá o acesso ao recurso que está sendo requisitado.

Body
O body é o corpo da mensagem que você quer enviar na requisição. Ele é utilizado somente nos métodos de POST, PUT e PATCH. Ele contém o dado a ser processado pela API e por isso não é necessário em métodos de leitura de dados (como o GET).

Por exemplo: Digamos que você queira adicionar uma nova empresa via API no PipeRun. Neste caso, utilizando o método POST, informará no body os dados que serão salvos, como o nome, endereço e contato da empresa. Algumas informações são obrigatórias de serem enviadas. Você pode conferir essas informações na documentação da API.

HTTPS Status Code
Para facilitar o entendimento das respostas das APIs existem padrões de códigos de status que podem ser utilizados.

Os códigos mais utilizados para as respostas de uma requisição são o 200 (ok), o 201 (created), o 204 (no content), o 404 (not found), o 400 (bad request), e 500 (internal server error).

Existem vários outros códigos de resposta do protocolo HTTP que podem ser utilizados. Neste link temos a lista completa.

Como padrão, os códigos de sucesso tem o prefixo 20x, os de redirecionamento 30x, os de erro do cliente 40x e os de erro de servidor 50x.

Autenticação
Não podemos falar de APIs sem segurança, afinal estamos falando de serviços WEB.

Como principais métodos de autenticação de APIs, temos:

• Basic authentication: Baseado em usuário e senha codificados em Base64 e utilizado no header da requisição;
• Secret token;
• Token de acesso que pode ser limitado a escopo, e que é enviado na requisição pelo Header ou pela Query String. Nesse caso temos padrões famosos como oAuth e JWT.

POR QUE USAR UMA API?

Como vimos, uma API pode mudar o dia a dia da empresa, agregando simplicidade, agilidade e automação aos sistemas. No CRM PipeRun, diversas integrações estão configuradas, buscando trazer facilidade de comunicação entre plataformas diferentes das áreas de marketing e vendas.

Portanto, a API pode ser utilizada para agregar agilidade em áreas da empresa, ou mesmo aperfeiçoar áreas estratégicas de importância. Por exemplo, uma organização que tem como meta para o ano dobrar o número de clientes pode adotar o uso de APIs na pré-venda para ter maior eficiência na qualificação e conversão de leads.

Em caso de dúvidas, entre em contato com nossa equipe de suporte.