O que é uma API?

O que é uma API, em termos simples?

API é a sigla em inglês para Application Programming Interface, ou interface de programação de aplicações. É um conjunto de regras que define como um software pode pedir dados ou ações a outro software. Quem usa a API não precisa saber como o outro sistema foi construído: basta seguir o que está documentado.

Uma comparação útil é o balcão de atendimento de uma empresa. Quem está do lado de fora não entra no estoque nem mexe nos arquivos. Faz um pedido no balcão, em um formato combinado, e recebe uma resposta. O balcão decide o que pode ser pedido, por quem e de que forma. A API cumpre esse papel entre sistemas.

Essa separação é o que torna a API valiosa. O sistema que oferece a API pode mudar por dentro, trocar de banco de dados ou de linguagem, e quem consome continua funcionando, desde que o contrato seja mantido.

Como funciona uma API na prática?

A maior parte das APIs usadas por empresas hoje funciona sobre HTTP, o mesmo protocolo que os navegadores usam para abrir páginas. A comunicação acontece em um ciclo de requisição e resposta.

1. O sistema cliente monta uma requisição, informando o endereço do recurso, o tipo de operação e, quando necessário, os dados enviados.
2. A requisição carrega uma credencial, que identifica quem está pedindo.
3. O sistema servidor valida a credencial e os dados recebidos.
4. O servidor executa a operação e devolve uma resposta, com um código de status e, em geral, dados em formato JSON.

Um exemplo de consulta a um pedido:

GET /pedidos/1042 HTTP/1.1
Host: api.exemplo.com
Authorization: Bearer <token>

E uma resposta possível:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 1042,
  "status": "faturado",
  "valor_total": 1890.50
}

O que são os métodos e os códigos de status?

Os métodos HTTP indicam a intenção da requisição, e os códigos de status indicam o resultado. Ambos são definidos pela especificação do HTTP, o que permite que sistemas de fornecedores diferentes se entendam.

Para quem gerencia um projeto, esses códigos importam porque determinam como a integração reage. Um erro de dados inválidos pede correção; um erro de indisponibilidade pede nova tentativa mais tarde.

Quais são os tipos de API?

As APIs podem ser classificadas por quem pode usá-las e pelo estilo técnico adotado. As duas classificações são independentes.

Por público

• API privada (interna): usada apenas dentro da empresa, para que os próprios sistemas conversem entre si. É o caso de um aplicativo que consome o back-end da mesma empresa.
• API de parceiros: aberta a empresas autorizadas, como distribuidores, transportadoras ou clientes corporativos.
• API pública: disponível para qualquer desenvolvedor que se cadastre, como as de meios de pagamento, mapas e envio de mensagens.

Por estilo técnico

Nenhum estilo é superior em todos os cenários. REST é o mais comum por ser simples e bem suportado por ferramentas. SOAP continua presente em sistemas que já existiam antes da popularização do REST. A escolha depende do que os sistemas envolvidos oferecem e do tipo de dado trocado.

Para que uma empresa usa APIs?

Uma empresa usa APIs sempre que precisa que dois softwares troquem informação sem intervenção manual. Alguns usos recorrentes:

• Enviar pedidos de uma loja virtual para o sistema de gestão.
• Emitir cobranças e receber a confirmação de pagamento.
• Consultar endereço a partir do CEP ou validar um cadastro.
• Alimentar painéis de indicadores com dados de vários sistemas.
• Permitir que um aplicativo de celular acesse os dados do sistema principal.
• Disponibilizar dados a clientes e parceiros de forma controlada.

Em todos esses casos, a API substitui uma tarefa que, sem ela, seria feita por alguém copiando dados de uma tela para outra ou exportando e importando planilhas. É por isso que APIs são a base de quase todo projeto de conexão entre sistemas. Explicamos o passo a passo desse tipo de projeto no artigo sobre como integrar dois sistemas.

APIs também são o ponto de partida de muitas automações. Quando os sistemas envolvidos oferecem API, um fluxo inteiro pode ser executado sem digitação. Para definir por onde começar, vale ler quais processos automatizar primeiro.

O que é preciso para uma API ser bem feita?

Uma API bem feita é previsível, segura e documentada. Esses três atributos determinam quanto custa usá-la e mantê-la ao longo do tempo.

Autenticação e controle de acesso

Toda requisição precisa identificar quem está pedindo. Os mecanismos mais comuns são chaves de API e tokens emitidos por fluxos como o OAuth 2.0. Além de identificar, a API deve limitar o que cada cliente pode fazer: um parceiro que consulta estoque não precisa ter permissão para alterar preços.

Documentação

A documentação descreve cada operação disponível, os dados esperados, as respostas possíveis e os erros. O padrão OpenAPI permite escrever essa descrição em um formato que pessoas e ferramentas conseguem ler. Uma API sem documentação obriga cada novo integrador a descobrir o comportamento por tentativa e erro.

Versionamento

Sistemas evoluem, e a API precisa evoluir sem quebrar quem já a utiliza. O versionamento permite lançar mudanças incompatíveis em uma nova versão, mantendo a anterior no ar por um período combinado.

Limites de uso e tratamento de erros

Limites de requisições protegem o sistema contra sobrecarga, intencional ou não. Mensagens de erro claras reduzem o tempo de diagnóstico: dizer qual campo está inválido é muito mais útil do que devolver apenas "erro".

Registro e monitoramento

Registrar quem chamou, quando e com qual resultado permite investigar problemas e identificar uso indevido. Sem registro, uma falha de integração vira uma discussão sobre de quem é a culpa.

Quando vale a pena criar uma API própria?

Criar uma API própria vale a pena quando a empresa tem um sistema cujos dados precisam ser acessados por outros softwares de forma recorrente e controlada. Situações típicas:

• A empresa vai lançar um aplicativo ou portal que depende dos dados do sistema principal.
• Clientes ou parceiros pedem acesso automatizado a informações, como posição de pedidos ou estoque.
• Vários sistemas internos acessam o mesmo banco de dados diretamente, e cada mudança na estrutura quebra algo.
• Um sistema antigo precisa continuar funcionando, mas novos módulos precisam conversar com ele.

Esse último caso é comum em projetos de modernização: colocar uma API na frente de um sistema antigo permite substituí-lo por partes, sem parar a operação. Tratamos desse cenário em sistema legado: quando modernizar.

Por outro lado, nem sempre uma API própria é necessária. Se a troca de dados acontece uma vez por mês, com baixo volume e sem urgência, um arquivo exportado pode resolver com custo menor. E se o sistema usado é um software de mercado que já oferece API, o trabalho é consumi-la bem, não construir outra.

Quando a API é de fato necessária, o projeto envolve definir recursos, permissões, formato de dados, documentação e monitoramento. É esse o escopo do nosso serviço de desenvolvimento de APIs sob medida.

O que levar deste artigo

API é um contrato entre sistemas: define o que pode ser pedido, como e por quem. Ela permite que softwares diferentes troquem dados sem digitação manual e sem que um precise conhecer o funcionamento interno do outro. Para uma empresa, entender o conceito ajuda em três decisões práticas: avaliar se um software de mercado pode ser integrado ao que já existe, saber o que perguntar a um fornecedor sobre a API oferecida e reconhecer quando vale a pena expor os próprios dados por uma API bem projetada.