O que é uma API? Guia simples para construtores de apps
Uma API (interface de programação de aplicações) é uma forma definida de um software pedir dados a outro ou de o levar a fazer algo. A sua app envia um pedido num formato acordado — «dá-me as marcações de amanhã», «cobra 20 € a este cartão», «resume este texto» — e o outro sistema devolve uma resposta estruturada. As APIs são a forma como as peças de uma app comunicam entre si, e como a sua app usa serviços externos como pagamentos, email, mapas e IA.
Porque importam as APIs quando constrói com IA
Quase todas as apps úteis são feitas de partes que comunicam através de APIs:
- Dentro da sua app, os ecrãs no navegador chamam a API do seu próprio backend para carregar e guardar dados.
- Fora da sua app, o seu backend chama as APIs de outras empresas: a Stripe para receber pagamentos, um fornecedor de email para enviar recibos, um fornecedor de modelos de IA para gerar texto.
Quando pede a um construtor de IA para «receber pagamentos» ou «acrescentar um resumo com IA», o que ele está de facto a fazer é escrever código que chama uma API. Perceber o básico ajuda-o a entender o que a IA precisa de si (normalmente uma conta nesse serviço e uma chave de API), onde podem surgir problemas e quanto vai custar.
Uma analogia do dia a dia
Pense num restaurante. Não entra na cozinha para cozinhar. Lê a ementa, diz ao empregado o que quer de forma que a cozinha perceba, e o empregado traz-lhe a comida — ou diz-lhe que o prato está esgotado.
- A ementa é a documentação da API: uma lista do que pode pedir e como.
- O empregado é a API: a forma única e acordada pela qual os pedidos entram e as respostas saem.
- A cozinha é o outro sistema: não precisa de saber como funciona por dentro.
- O seu pedido é o pedido; o prato é a resposta.
A cozinha pode mudar os seus fornos e o pessoal sem o afetar, desde que a ementa se mantenha. Esse é o verdadeiro valor de uma API: permite que dois sistemas trabalhem juntos sem que nenhum precise de saber como o outro está construído.
Como funciona um pedido de API web
A maioria das APIs com que vai lidar são APIs web que funcionam sobre HTTP, o mesmo protocolo que o seu navegador usa. Cada pedido tem algumas partes:
| Parte | O que é | Exemplo |
|---|---|---|
| Método | O tipo de ação | GET (ler), POST (criar) |
| URL / endpoint | O endereço da coisa sobre a qual atua | https://api.exemplo.com/bookings |
| Cabeçalhos | Informação extra, incluindo quem é | Authorization: Bearer <a sua chave> |
| Corpo | Os dados que envia, para criar e atualizar | {"name": "Lena", "time": "14:00"} |
E cada resposta tem:
| Parte | O que é | Exemplo |
|---|---|---|
| Código de estado | Um número que indica como correu | 200 OK, 201 Created, 404 Not Found |
| Corpo | Os dados devolvidos, normalmente em JSON | {"id": 5001, "status": "confirmed"} |
JSON (JavaScript Object Notation) é um formato de texto simples com nomes e valores entre chavetas. É o formato padrão para trocar dados em APIs web.
REST: o estilo mais comum
REST é uma convenção amplamente usada para desenhar APIs web. Cada tipo de coisa tem o seu próprio URL, e os métodos padrão indicam o que se faz com ela. Eis como poderia ser uma API REST para uma app de marcações:
| Método | Endpoint | O que faz |
|---|---|---|
GET | /api/bookings | Listar marcações |
GET | /api/bookings/5001 | Obter uma marcação |
POST | /api/bookings | Criar uma nova marcação |
PATCH | /api/bookings/5001 | Alterar parte de uma marcação, como a hora |
DELETE | /api/bookings/5001 | Cancelar (apagar) uma marcação |
PUT também existe e, por convenção, substitui um registo inteiro, enquanto PATCH altera apenas os campos que envia.
Os códigos de estado que vai ver com mais frequência:
| Código | Significado |
|---|---|
200 / 201 | Sucesso / criado |
400 | Pedido inválido — algo no que enviou estava errado ou em falta |
401 | Não autenticado — sem início de sessão ou chave válidos |
403 | Proibido — é conhecido, mas não tem permissão para fazer isto |
404 | Não encontrado |
429 | Demasiados pedidos — atingiu um limite de utilização |
500 | O servidor teve um erro |
Quando a sua app avaria, o código de estado é muitas vezes a pista mais rápida. Um 401 de um fornecedor de pagamentos normalmente significa uma chave de API em falta ou errada; um 429 significa que está a chamar com demasiada frequência.
REST não é o único estilo — existem também GraphQL e APIs de estilo RPC — mas REST é o que a maioria dos serviços e backends construídos com IA usa.
Um exemplo prático: a confirmação de uma marcação
Quando um cliente marca um corte de cabelo numa app de salão, podem acontecer várias chamadas de API em um ou dois segundos:
- A página de marcação no navegador envia
POST /api/bookingscom o serviço, a hora e os dados do cliente para o seu backend. - O seu backend verifica se o horário está livre, guarda a marcação na base de dados e devolve
201 Created. - O seu backend chama a API de um fornecedor de email com a sua chave secreta: «envia esta confirmação para lena@exemplo.pt».
- Se houver um sinal, o seu backend pede à API do fornecedor de pagamentos que crie uma sessão de checkout e envia o cliente para lá.
- Mais tarde, o fornecedor de pagamentos chama a sua app para dizer que o pagamento foi aprovado. Essa chamada no sentido inverso é um webhook.
Os dois primeiros passos são a sua própria API entre o frontend e o backend. Os passos 3 a 5 são APIs de terceiros.
Termos comuns explicados
| Termo | Significado |
|---|---|
| Endpoint | Um URL específico ao qual uma API responde. |
| Chave de API | Uma cadeia secreta que identifica a sua app perante um serviço. Trate-a como uma palavra-passe. |
| Autenticação | Provar quem está a chamar — com uma chave, um token ou um início de sessão. Veja o que é a autenticação. |
| Limite de pedidos (rate limit) | Um teto para o número de pedidos que pode fazer num período. |
| SDK | Uma biblioteca de código pronta a usar que facilita chamar uma determinada API. |
| Documentação | A «ementa»: que endpoints existem, o que aceitam e o que devolvem. |
| Sandbox / modo de teste | Uma versão de um serviço para testar sem dinheiro real nem dados reais. |
| Webhook | Uma chamada de outro serviço para a sua app quando algo acontece. |
Erros comuns e ideias erradas
- Pôr chaves secretas no frontend. Tudo o que está no código que corre no navegador pode ser visto por qualquer pessoa que visite o site. As chaves secretas têm de ficar no servidor, em variáveis de ambiente ou segredos.
- Colar chaves no chat. O histórico do chat pode ser guardado. Use antes a funcionalidade de segredos do seu construtor, e rode qualquer chave que tenha ficado exposta.
- Assumir que uma API é gratuita. Muitas APIs cobram por pedido ou por unidade de utilização — as APIs de modelos de IA cobram por tokens. Verifique os preços e defina limites de gastos. Veja como usar APIs de LLM.
- Não tratar falhas. Os serviços externos ficam em baixo, têm timeouts e atingem limites. Peça mensagens de erro sensatas e novas tentativas.
- Confiar no navegador. A sua própria API tem de verificar as permissões. Esconder um botão não impede alguém de chamar o endpoint diretamente.
- Usar chaves ativas durante os testes. Use chaves de modo de teste até estar pronto para lançar.
O que pedir ao seu construtor de IA
- «Quais são as APIs externas que esta app usa, e quanto custa cada uma?»
- «Chama a API de pagamentos apenas a partir do servidor. Lê a chave a partir de uma variável de ambiente.»
- «Lista cada endpoint da nossa API, o que faz e quem tem permissão para o chamar.»
- «Verifica no servidor que o utilizador com sessão iniciada é dono da marcação antes de a atualizar ou apagar.»
- «Se a API de email falhar, guarda a marcação na mesma e regista o erro.»
- «Usa, por agora, o modo de teste do fornecedor.»
APIs no Mythex
O Mythex pode construir a sua própria API — como parte de uma app web, ou como um backend separado em Node, Python (FastAPI), C# ou Java a correr junto ao seu frontend — e escrever o código que chama serviços externos. Acrescenta as chaves deles como segredos do projeto e não no chat, e ficam disponíveis para a sua app na pré-visualização e depois de publicada. A documentação tem receitas para integrar qualquer API e construir um backend de API REST.
Perguntas
O que é uma API, em termos simples?
Uma API (interface de programação de aplicações) é uma forma definida de um software pedir dados ou pedir a outro que faça algo. A sua app envia um pedido num formato acordado, e o outro sistema devolve uma resposta — como dados meteorológicos, o resultado de um pagamento ou uma resposta gerada por IA.
O que é uma API REST?
Uma API REST é um estilo comum de API web em que cada tipo de coisa (marcações, clientes) tem um URL, e usa-se os métodos HTTP padrão — GET para ler, POST para criar, PUT ou PATCH para atualizar, DELETE para remover. Os dados costumam voltar em JSON.
O que é uma chave de API e onde a devo guardar?
Uma chave de API é uma cadeia secreta que identifica a sua app perante um serviço e que muitas vezes lhe permite gastar dinheiro ou aceder a dados. Guarde-a em variáveis de ambiente ou nos segredos do projeto, no servidor, nunca em código que corre no navegador e nunca num repositório público.
Qual é a diferença entre uma API e um webhook?
Com uma API, a sua app pede algo a outro serviço quando quer. Com um webhook, o outro serviço chama a sua app quando algo acontece — por exemplo, um fornecedor de pagamentos a avisar que um pagamento foi aprovado.