O que é uma API e como ela conecta sistemas

Você está usando um app de clima no celular. Ele mostra temperatura, umidade, previsão para a semana. O app não tem satélite próprio, não processa dados meteorológicos — ele pede isso para outra empresa. A pergunta é: como ele pede? A resposta é API.

Esse exemplo é mais útil que a definição clássica de livro porque deixa claro que API não é um produto isolado — é a ponte entre dois sistemas que precisam trocar informação sem se conhecer por dentro.

O que é uma API, exatamente

API significa Application Programming Interface. Em português, interface de programação de aplicações — um nome que explica tudo e ao mesmo tempo não ajuda ninguém.

Uma definição mais útil: uma API é um contrato. Ela diz: "se você me enviar uma request nesse formato, eu te devolvo uma response nesse formato". O que acontece por dentro para processar isso é problema meu; você não precisa saber.

É o mesmo princípio de um controle remoto. Você aperta "aumentar volume" e o som sobe. Você não precisa entender o circuito interno da TV — só precisa saber qual botão apertar e o que esperar que aconteça.

No mundo de software, APIs permitem que sistemas desenvolvidos por empresas diferentes, em linguagens diferentes, rodando em servidores diferentes, se comuniquem como se fossem partes do mesmo sistema.

Request e response: a unidade básica de comunicação

Toda comunicação via API funciona em ciclos de request/response:

1. Um sistema envia uma request (pedido) para a API
2. A API processa
3. A API devolve uma response (resposta) com o resultado

Isso vale para qualquer tipo de API, mas quando falamos de APIs web — as mais comuns hoje — o transporte é HTTP, o mesmo protocolo que o navegador usa para carregar sites.

Uma request HTTP tem algumas partes essenciais:

• Método: o que você quer fazer (GET, POST, PUT, DELETE)
• URL: para onde você está enviando o pedido
• Headers: metadados da request (tipo do conteúdo, autenticação, etc.)
• Body (opcional): os dados que você está enviando

Uma response tem estrutura parecida:

• Status code: número que indica o resultado (200 OK, 404 Not Found, 500 Internal Server Error)
• Headers: metadados da response
• Body: os dados que você recebeu de volta

GET https://api.openweathermap.org/data/2.5/weather?q=São+Paulo

Essa request usa o método GET (buscar dados), aponta para um endpoint específico e passa o nome da cidade como parâmetro. A API responde com um JSON contendo temperatura, condição climática, umidade — o que o app de clima vai mostrar para o usuário.

Endpoints: os pontos de acesso da API

Um endpoint é uma URL específica que expõe uma funcionalidade da API. É literalmente onde você bate para pedir alguma coisa.

Uma API de e-commerce pode ter endpoints como:

GET    /products           → lista todos os produtos
GET    /products/42        → retorna o produto com id 42
POST   /products           → cria um novo produto
PUT    /products/42        → atualiza o produto 42
DELETE /products/42        → remove o produto 42

Note que o mesmo recurso (/products) tem comportamentos diferentes dependendo do método HTTP usado. Isso é a essência do REST — falaremos mais sobre isso abaixo.

Cada endpoint é projetado para fazer uma coisa bem feita. Você não manda um GET /products esperando que ele também crie um produto — existe um endpoint separado para isso, com método POST.

JSON: o formato que dominou as APIs

Quando a API devolve dados, ela precisa de um formato que o sistema solicitante consiga ler. Hoje o formato dominante é JSON — JavaScript Object Notation.

Apesar do nome mencionar JavaScript, JSON não é exclusivo da linguagem. Qualquer sistema moderno consegue ler e escrever JSON. É texto puro, estruturado, legível por humanos:

{
  "city": "São Paulo",
  "temperature": 22.5,
  "unit": "celsius",
  "conditions": "partly cloudy",
  "forecast": [
    { "day": "segunda", "high": 25, "low": 18 },
    { "day": "terça", "high": 27, "low": 19 }
  ]
}

Cada campo tem uma chave (string) e um valor, que pode ser texto, número, booleano, array ou outro objeto. A estrutura aninhada permite representar dados complexos de forma limpa.

Antes do JSON, XML era o padrão — mais verboso, mais difícil de parsear. Se você já viu aquelas APIs de SOAP da era dos bancos, sabe a diferença na prática.

REST: o estilo que todo mundo usa (e poucos definem direito)

Quando alguém fala "API REST" ou "RESTful API", está falando de um estilo arquitetural — não um protocolo, não uma especificação, não uma linguagem. REST (Representational State Transfer) é um conjunto de convenções para construir APIs HTTP.

As principais:

Recursos e URLs: cada URL representa um recurso (/users, /orders/123, /products). Não /getUsers ou /createProduct — ações ficam no método HTTP, não na URL.

Métodos HTTP com semântica: GET busca sem modificar, POST cria, PUT/PATCH atualiza, DELETE remove. Usar GET para deletar dados é uma receita para desastre — especialmente quando há caches no caminho.

Stateless: cada request contém tudo que a API precisa para processá-la. O servidor não guarda estado da sessão entre requests. Autenticação vai no header de cada request, não em "você está logado desde a request anterior".

Representação: o cliente recebe uma representação do recurso, não o recurso em si. Você pede /users/42 e recebe um JSON com os dados do usuário — a API decide o formato da resposta.

REST não é uma especificação formal, então duas "APIs REST" podem ter convenções bem diferentes. Na prática, a maioria do que chamamos de REST hoje é melhor descrito como "JSON over HTTP com URLs razoáveis".

Status codes: o primeiro lugar onde olhar quando algo falha

Quando uma request dá errado, o status code da response é o primeiro lugar para olhar. Eles são organizados em faixas:

• 2xx: sucesso. 200 OK, 201 Created, 204 No Content.
• 3xx: redirecionamento. O recurso mudou de lugar.
• 4xx: erro do cliente. Você mandou algo errado. 400 Bad Request (request malformada), 401 Unauthorized (falta autenticação), 403 Forbidden (autenticado mas sem permissão), 404 Not Found (recurso não existe).
• 5xx: erro do servidor. O problema é no lado da API. 500 Internal Server Error, 503 Service Unavailable.

A distinção entre 4xx e 5xx importa: 4xx significa que você precisa corrigir a request; 5xx significa que você precisa aguardar ou acionar o suporte da API.

{
  "error": "invalid_request",
  "message": "O campo 'email' é obrigatório",
  "status": 400
}

Quando estou integrando uma API nova, mantenho o HTTP Status Codes aberto ao lado — útil para confirmar o que cada código significa quando a documentação é vaga.

Um exemplo real, passo a passo

Vamos simular o que acontece quando um app de delivery mostra o cardápio:

1. O app envia uma request:

GET /restaurants/123/menu
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

2. A API verifica o token de autorização, busca os dados no banco, monta a response.

3. A API devolve:

{
  "restaurant_id": 123,
  "name": "Pizzaria Napolitana",
  "menu": [
    {
      "id": 1,
      "name": "Margherita",
      "price": 45.90,
      "available": true
    },
    {
      "id": 2,
      "name": "Pepperoni",
      "price": 52.50,
      "available": false
    }
  ]
}

4. O app recebe o JSON, renderiza os itens na tela, mostra "indisponível" para o Pepperoni.

Nenhum HTML, nenhum CSS — só dados. O app decide como apresentar. A API decide como armazenar e processar. Essa separação de responsabilidades é o que permite que o mesmo backend alimente um app iOS, um Android, e uma aplicação web.

Perguntas frequentes

O que é autenticação em API?

Antes de processar qualquer request, a maioria das APIs verifica quem está pedindo. Os métodos mais comuns são: API Key (uma string secreta enviada no header ou query string), Bearer Token (um JWT ou token de sessão no header Authorization), e OAuth 2.0 (para autorização delegada — é o "Login com Google" que você usa em outros apps).

Sem autenticação, qualquer pessoa poderia usar sua API com sua quota, acessar dados que não são dela, ou fazer operações destrutivas.

REST é a única forma de construir APIs?

Não. GraphQL é uma alternativa popular onde o cliente define exatamente quais campos quer na response — útil quando o cliente precisa de flexibilidade e o overfetching de REST é um problema real. gRPC é outra alternativa, baseada em Protocol Buffers, comum em comunicação entre microserviços por ser mais compacto e eficiente que JSON. SOAP ainda existe em sistemas legados, especialmente em bancos e governo.

O que é rate limiting?

APIs geralmente limitam quantas requests você pode fazer em um período de tempo. Se passar do limite, você recebe 429 Too Many Requests. Rate limiting existe para proteger a infraestrutura da API de abuso e garantir disponibilidade para todos os consumidores. Quando integrar uma API externa, leia a documentação de rate limits antes de começar.

API pública vs. privada: qual a diferença?

API pública é acessível por qualquer desenvolvedor (às vezes com cadastro e API key). Exemplo: API do Mercado Livre, OpenWeather, Stripe. API privada é usada internamente pela própria empresa — o frontend do site conversando com o backend. API de parceiro fica no meio: acessível para parceiros de negócio específicos, com contratos de acesso.

API não é mágica, é contrato

API é uma das ideias mais simples da computação moderna — e uma das mais poderosas exatamente por isso. Um contrato claro entre sistemas permite que equipes trabalhem independentemente, que serviços escalem separadamente, e que empresas vendam acesso às suas funcionalidades como produto.

Se você está começando a trabalhar com APIs, os três conceitos que mais vão aparecer são: entender o que cada endpoint faz, ler os status codes da response quando algo falha, e consultar a documentação antes de assumir o formato dos dados. O resto é prática.