O que é uma API? Um guia em linguagem simples para criadores de apps

Uma API (interface de programação de aplicações) é uma forma definida de um software pedir dados a outro ou fazer com que ele execute algo. Seu app envia uma requisição em um formato combinado — "me dê os agendamentos de amanhã", "cobre 20 euros neste cartão", "resuma este texto" — e o outro sistema devolve uma resposta estruturada. As APIs são como as partes de um app conversam entre si, e como seu app usa serviços externos como pagamentos, e-mail, mapas e IA.

Por que as APIs importam quando você cria com IA

Quase todo app útil é feito de partes que se comunicam por APIs:

• Dentro do seu app, as telas no navegador chamam a API do seu próprio backend para carregar e salvar dados.
• Fora do seu app, seu backend chama as APIs de outras empresas: o Stripe para receber pagamentos, um provedor de e-mail para enviar recibos, um provedor de modelos de IA para gerar texto.

Quando você pede a um criador com IA para "aceitar pagamentos" ou "adicionar um resumo com IA", o que ele realmente faz é escrever código que chama uma API. Conhecer o básico ajuda você a entender o que a IA precisa de você (geralmente uma conta nesse serviço e uma chave de API), onde as coisas podem dar errado e quanto vão custar.

Uma analogia do dia a dia

Pense em um restaurante. Você não entra na cozinha para cozinhar. Lê o cardápio, diz ao garçom o que quer de um jeito que a cozinha entende, e o garçom traz o seu prato — ou avisa que o prato acabou.

• O cardápio é a documentação da API: a lista do que você pode pedir e como.
• O garçom é a API: a única forma combinada de os pedidos entrarem e as respostas saírem.
• A cozinha é o outro sistema: você não precisa saber como ela funciona por dentro.
• Seu pedido é a requisição; o prato é a resposta.

A cozinha pode trocar seus fornos e sua equipe sem afetar você, desde que o cardápio continue o mesmo. Esse é o valor real de uma API: deixar dois sistemas trabalharem juntos sem que nenhum precise saber como o outro foi construído.

Como uma requisição de API web funciona

A maioria das APIs que você vai encontrar são APIs web que funcionam sobre HTTP, o mesmo protocolo que o seu navegador usa. Cada requisição tem algumas partes:

E cada resposta tem:

JSON (JavaScript Object Notation) é um formato de texto simples, com nomes e valores entre chaves. É a forma padrão de as APIs web trocarem dados.

REST: o estilo mais comum

REST é uma convenção amplamente usada para desenhar APIs web. Cada tipo de coisa recebe sua própria URL, e métodos padrão dizem o que você está fazendo com ela. Veja como uma API REST para um app de agendamentos poderia ser:

PUT também existe e, por convenção, substitui um registro inteiro, enquanto PATCH altera apenas os campos que você envia.

Os códigos de status que você mais vai ver:

Quando seu app quebra, o código de status costuma ser a pista mais rápida. Um 401 de um provedor de pagamentos geralmente significa uma chave de API ausente ou errada; um 429 significa que você está chamando com frequência demais.

REST não é o único estilo — existem também GraphQL e APIs no estilo RPC —, mas REST é o que a maioria dos serviços e backends criados com IA usa.

Um exemplo prático: a confirmação de um agendamento

Quando um cliente marca um corte de cabelo em um app de salão, várias chamadas de API podem acontecer em um ou dois segundos:

1. A página de agendamento no navegador envia POST /api/bookings com o serviço, o horário e os dados do cliente para o seu backend.
2. Seu backend verifica se o horário está livre, salva o agendamento no banco de dados e devolve 201 Created.
3. Seu backend chama a API de um provedor de e-mail com a chave secreta: "envie esta confirmação para lena@example.com".
4. Se houver um sinal de pagamento, seu backend pede à API do provedor de pagamentos que crie uma sessão de checkout e envia o cliente para lá.
5. Depois, o provedor de pagamentos chama o seu app para dizer que o pagamento foi aprovado. Essa chamada no sentido inverso é um webhook.

As duas primeiras etapas são a sua própria API entre frontend e backend. As etapas 3 a 5 são APIs de terceiros.

Termos comuns explicados

Erros comuns e ideias erradas

• Colocar chaves secretas no frontend. Tudo o que está em código que roda no navegador pode ser visto por qualquer pessoa que visite o site. Chaves secretas devem ficar no servidor, em variáveis de ambiente ou segredos.
• Colar chaves no chat. O histórico do chat pode ser armazenado. Use o recurso de segredos do seu criador, e troque qualquer chave que você tenha exposto.
• Presumir que uma API é gratuita. Muitas APIs cobram por requisição ou por unidade de uso — APIs de modelos de IA cobram por tokens. Confira os preços e defina limites de gasto. Veja como usar APIs de LLM.
• Não tratar falhas. Serviços externos caem, dão timeout e atingem limites. Peça mensagens de erro sensatas e novas tentativas.
• Confiar no navegador. Sua própria API precisa verificar as permissões por conta própria. Esconder um botão não impede que alguém chame o endpoint diretamente.
• Usar chaves de produção durante os testes. Use as chaves do modo teste até estar pronto para lançar.

O que pedir ao seu criador de apps com IA

• "Quais APIs externas este app usa, e quanto cada uma custa?"
• "Chame a API de pagamento somente a partir do servidor. Leia a chave de uma variável de ambiente."
• "Liste cada endpoint da nossa API, o que ele faz e quem tem permissão para chamá-lo."
• "Verifique no servidor que o usuário logado é dono do agendamento antes de atualizá-lo ou excluí-lo."
• "Se a API de e-mail falhar, salve o agendamento mesmo assim e registre o erro."
• "Por enquanto, use o modo teste do provedor."

APIs no Mythex

O Mythex pode construir a sua própria API — como parte de um app web, ou como um backend separado em Node, Python (FastAPI), C# ou Java rodando junto com o seu frontend — e escrever o código que chama serviços externos. Você adiciona as chaves deles como segredos do projeto, e não no chat, e elas ficam disponíveis para o seu app na prévia e depois de publicado. A documentação tem receitas para integrar qualquer API e criar um backend de API REST.

Perguntas