O que é uma API? Explicação simples com exemplos práticos

Já ouviste "vamos ligar via API" ou "esse serviço tem uma API"? Uma API é uma forma de dois programas falarem entre si. Se queres trabalhar com web, aplicações ou automação, vais usá-las constantemente. Aqui fica uma explicação sem palavreado.

A analogia do empregado de mesa

Num restaurante, não vais à cozinha pedir o prato. Falas com o empregado, que leva o pedido à cozinha e traz a resposta. O empregado é a API: um intermediário com regras claras sobre o que podes pedir e como.

API vem de Application Programming Interface: "interface de programação de aplicações".

Exemplos reais

• A aplicação meteorológica do telemóvel pede à API de um serviço de meteorologia a previsão para a tua cidade.
• Uma loja online usa a API de um serviço de pagamentos para cobrar o cartão.
• Um site mostra um mapa através da API de um serviço de mapas.
• Um bot de mensagens usa a API da plataforma para enviar e receber mensagens.

Pedido e resposta

Uma API web funciona sobre HTTP (vê como funciona a internet). Envias um pedido para um endereço e recebes uma resposta.

Métodos HTTP principais:

• GET: pedir dados.
• POST: enviar dados novos.
• PUT ou PATCH: atualizar.
• DELETE: apagar.

O formato JSON

A maioria das APIs responde em JSON, um formato de texto simples que representa dados:

{
  "nome": "Maria",
  "idade": 21,
  "cursos": ["Informática", "Inglês"],
  "ativa": true
}

É fácil de ler por humanos e por programas, e praticamente todas as linguagens o suportam.

Chamar uma API com JavaScript

async function obterUtilizador() {
  const resposta = await fetch("https://jsonplaceholder.typicode.com/users/1");

  if (!resposta.ok) {
    throw new Error("Erro: " + resposta.status);
  }

  const dados = await resposta.json();
  console.log(dados.name, dados.email);
}

obterUtilizador();

O fetch faz o pedido, o await espera pela resposta e .json() converte o texto em dados utilizáveis. Podes testar no separador Consola do navegador.

Chamar uma API com Python

import requests

resposta = requests.get("https://jsonplaceholder.typicode.com/users/1")
resposta.raise_for_status()
dados = resposta.json()
print(dados["name"], dados["email"])

Chaves de API e autenticação

Muitas APIs exigem uma chave para saberem quem és e limitarem o uso. Regras importantes:

1. Nunca coloques a chave diretamente no código que vai para o GitHub.
2. Guarda-a em variáveis de ambiente ou num ficheiro de configuração fora do repositório.
3. Se a chave for exposta, revoga-a e cria outra.

Códigos de resposta

• 200: sucesso.
• 201: criado com sucesso.
• 400: pedido mal formado.
• 401 ou 403: sem autenticação ou sem permissão.
• 404: recurso não existe.
• 429: pediste demasiadas vezes.
• 500: erro do servidor.

Criar a tua própria API

Mais tarde, no backend, vais criar APIs para o teu site ou aplicação. Os princípios são os mesmos: definir endereços, aceitar pedidos, validar dados, responder em JSON e proteger o acesso. Antes disso, convém perceber frontend e backend e dominar SQL.