O que é API: guia definitivo para iniciantes (com exemplos práticos)

API aparece em todo lugar no desenvolvimento de software, mas a explicação técnica padrão — “Application Programming Interface” — diz pouco para quem está começando. A explicação mais útil é a analogia do restaurante: você (o cliente) não entra na cozinha para pegar sua comida diretamente. Você faz um pedido para o garçom (a API), que leva o pedido à cozinha (o sistema/servidor), e traz de volta o que você pediu. Você não precisa saber como a cozinha funciona — só precisa saber o que pode pedir e como pedir.

Por que APIs existem?

APIs existem para permitir que sistemas diferentes se comuniquem sem precisar compartilhar código interno ou banco de dados. Quando você clica em “Login com Google” em um site qualquer, esse site está usando a API do Google para verificar sua identidade — sem ter acesso à sua senha, sem saber como o Google armazena seus dados. O Google expõe uma API que qualquer site pode usar para autenticação. Quando você usa um app de delivery e aparece o mapa com a localização do entregador, o app está consumindo a API do Google Maps. APIs são o que torna possível a internet moderna de serviços interconectados.

API REST: o padrão mais usado na web

REST (Representational State Transfer) é o estilo arquitetural mais popular para APIs web. Uma API REST funciona sobre HTTP — o mesmo protocolo que o seu browser usa para acessar sites. Os métodos HTTP principais:

• GET — buscar/ler dados. “Me dê a lista de produtos” ou “Me dê o produto #42”
• POST — criar algo novo. “Crie este novo pedido”
• PUT/PATCH — atualizar. “Atualize o endereço deste cliente”
• DELETE — remover. “Delete este item do carrinho”

A URL da requisição identifica o “recurso” (o quê): https://api.loja.com/produtos — a lista de produtos. https://api.loja.com/produtos/42 — o produto de ID 42. O método HTTP identifica a “ação” (o que fazer com ele). Juntos, URL + método HTTP descrevem completamente a operação.

JSON: a linguagem das APIs

APIs REST quase universalmente retornam dados em formato JSON (JavaScript Object Notation) — um formato de texto leve e legível por humanos que todas as linguagens de programação conseguem parsear. Um exemplo de resposta de API de usuário:

{
  "id": 42,
  "nome": "Maria Silva",
  "email": "maria@exemplo.com",
  "ativo": true,
  "endereco": {
    "cidade": "São Paulo",
    "estado": "SP"
  },
  "pedidos": [1201, 1205, 1210]
}

Objetos são delimitados por chaves, arrays por colchetes, strings por aspas duplas. Qualquer linguagem de programação tem suporte nativo ou biblioteca para parsear JSON para objetos/dicionários nativos da linguagem.

Consumindo uma API com Python

A biblioteca requests do Python torna consumir APIs REST trivial:

import requests

# Buscando dados de uma API pública de CEP
response = requests.get("https://viacep.com.br/ws/01310100/json/")

if response.status_code == 200:
    dados = response.json()  # Converte JSON para dicionário Python
    print(f"Rua: {dados['logradouro']}")
    print(f"Bairro: {dados['bairro']}")
    print(f"Cidade: {dados['localidade']}/{dados['uf']}")
else:
    print(f"Erro: {response.status_code}")

Instale com pip install requests se ainda não tiver. response.status_code é o código HTTP (200 = OK, 404 = não encontrado, 500 = erro no servidor). response.json() converte a resposta JSON automaticamente para dicionário Python.

Autenticação: como as APIs sabem quem você é

APIs públicas abertas (como a de CEP acima) não precisam de autenticação. APIs que retornam dados privados precisam saber quem está fazendo a requisição. Os métodos mais comuns: API Key — uma chave única enviada no header ou parâmetro da requisição. Bearer Token (JWT) — um token obtido após login, enviado no header Authorization: Bearer {token}. OAuth 2.0 — o protocolo por trás do “Login com Google/Facebook”, que permite acesso delegado sem compartilhar senhas. Quando você se cadastra em uma API (OpenAI, Stripe, Google Maps), recebe uma API Key que deve ser mantida secreta — nunca colocada diretamente no código ou commitada no Git.

Como praticar

Existem dezenas de APIs públicas e gratuitas perfeitas para praticar: ViaCEP (CEP brasileiros), Open-Meteo (clima, sem registro), PokeAPI (Pokémon, sem autenticação), JSONPlaceholder (dados fake para teste). Experimente fazer requisições GET com Python ou direto no browser. Depois experimente APIs que requerem API Key: OpenWeatherMap, NewsAPI, ou a API do GitHub. Cada API tem documentação que descreve os endpoints disponíveis, parâmetros aceitos e formatos de resposta — aprender a ler documentação de API é uma habilidade fundamental no desenvolvimento moderno.