Você informa dois endereços em um aplicativo e, segundos depois, recebe a distância, o tempo estimado e um caminho no mapa. A tela parece ter resolvido tudo sozinha. Em muitos casos, porém, ela organizou o pedido e o enviou a outro serviço, especializado em calcular rotas.
Essa conversa pode acontecer por meio de uma API, sigla em inglês para interface de programação de aplicações. É um nome amplo para a interface que permite a um programa usar recursos oferecidos por outro. Neste exemplo, estamos falando de uma API da web.
A tela foi feita para pessoas. Ela tem campos, botões e mensagens. A API foi feita para software. No lugar dos botões, existem regras sobre o endereço para o qual o pedido será enviado, a operação permitida, os dados necessários e o formato da resposta. Por isso, a metáfora da ponte ajuda, mas não conta a história inteira. Uma ponte apenas liga dois pontos; uma API também define como a comunicação deve acontecer.
Do toque na tela ao pedido
Nesse cenário, o aplicativo envia ao serviço de rotas um pedido estruturado. Origem, destino, meio de transporte e preferências ocupam campos previstos. A documentação da Routes API do Google, por exemplo, mostra uma solicitação com origem, destino e opções de viagem, seguida por uma resposta que pode conter duração, distância e os dados usados para desenhar o caminho.
O pedido também precisa indicar o que deve ser feito. Consultar uma informação, criar um registro e alterar um dado são intenções diferentes. Em muitas APIs, ele ainda leva uma chave ou outro tipo de credencial para identificar o programa que está fazendo a chamada e verificar sua permissão.
Essas combinações não precisam ficar apenas numa explicação escrita. A especificação OpenAPI permite descrever de forma padronizada endereços, caminhos, operações, parâmetros, respostas e requisitos de segurança. É uma maneira de tornar o acordo legível por pessoas e também por ferramentas.
A resposta ainda precisa virar tela
Depois de processar o pedido, o serviço devolve uma resposta estruturada. O aplicativo recebe os dados e decide como apresentá-los. Um número de duração vira “18 minutos”. Uma sequência de coordenadas vira a linha colorida sobre o mapa.
A resposta também costuma informar o resultado da operação. O padrão HTTP, descrito na RFC 9110, organiza essa troca em pedidos e respostas. Códigos na faixa 200 indicam sucesso; códigos 400 apontam problemas atribuídos ao pedido; códigos 500 indicam que o servidor falhou ao atender uma solicitação aparentemente válida.
Também pode não chegar resposta alguma. A conexão cai, o serviço demora demais ou fica indisponível. O aplicativo que iniciou a conversa precisa decidir se tenta de novo, registra a falha ou mostra uma mensagem.
É isso que a frase “o sistema tem API” deveria tornar possível: um programa pedir algo em um formato conhecido e saber interpretar o retorno. Ainda faltam decisões de implementação. Para tornar a promessa concreta, vale perguntar o que a API permite consultar ou fazer, quais dados e permissões exige e o que devolve quando a operação funciona ou falha. A conversa entre sistemas começa quando essas regras deixam de ser uma promessa e viram um acordo que os dois lados conseguem cumprir.
