APIs no Desenvolvimento Web: o que você realmente precisa entender

Quando a gente fala em desenvolvimento web moderno, não tem como fugir de um conceito: APIs.
Sites, apps mobile, painéis administrativos, integrações com terceiros… tudo conversa via API.

Se você quer evoluir como dev, principalmente no backend com Node.js, entender APIs não é opcional.

Neste post, vamos ver:

O que é uma API (na prática)
Conceitos básicos de APIs HTTP (REST)
Estrutura de uma requisição e resposta
Um exemplo simples de API em Node.js com Express
Como um frontend consome essa API
Boas práticas essenciais

O que é uma API?

API significa Application Programming Interface – Interface de Programação de Aplicações.

Traduzindo pro “mundo real”:

É uma forma padronizada de um sistema se comunicar com outro.

Em desenvolvimento web, normalmente estamos falando de APIs HTTP:
O cliente (navegador, app mobile, outro servidor) faz uma requisição HTTP, e o servidor responde com dados, normalmente em JSON.

Exemplos do dia a dia:

Quando você faz login em um site → o frontend chama uma API /login.
Quando um app de clima mostra a previsão → ele chama uma API de terceiros.
Quando você consulta um CEP → seu sistema chama uma API como ViaCEP.

Conceitos básicos de APIs HTTP (REST)

A maioria das APIs modernas segue princípios REST (não é uma regra absoluta, mas é muito comum).

Alguns conceitos essenciais:

1. Endpoints

São os “endereços” da API:

GET /users
POST /users
GET /users/10
DELETE /users/10

Pense como “rotas” que representam recursos.

2. Métodos HTTP

Os mais usados:

GET → buscar dados
POST → criar algo novo
PUT → atualizar totalmente
PATCH → atualizar parcialmente
DELETE → deletar

Exemplo:

GET /lives → lista lives
POST /lives → cria uma live
GET /lives/1 → busca a live de id 1

3. Status Codes

O servidor SEMPRE responde com um status. Alguns clássicos:

200 OK → deu bom
201 Created → recurso criado
400 Bad Request → requisição inválida
401 Unauthorized → não autenticado
404 Not Found → não encontrado
500 Internal Server Error → erro no servidor

Só de olhar o status você já entende o que aconteceu.

Estrutura básica de uma requisição

Uma chamada HTTP tem:

URL → https://api.meusite.com/users
Método → GET, POST, etc.
Headers → metadados (ex: Authorization, Content-Type)
Body → o conteúdo enviado (em POST, PUT, PATCH), normalmente JSON.

Exemplo de body em JSON:

{
“nome”: “Bernardo”,
“email”: “bernardo@teste.com”
}

Boas práticas básicas ao trabalhar com APIs

Só pra fechar com o que realmente importa no dia a dia:

Sempre retorne JSON estruturado
Nada de misturar string solta com JSON.
Use status codes corretamente
200 pra sucesso, 201 pra criação, 400+ pra erros do cliente, 500 pra erro interno.
Valide os dados de entrada
Nunca confie no que vem da requisição. Validação é obrigatória.
Pense em versionamento
Ex: /api/v1/lives. Isso evita quebrar clientes quando você mudar a estrutura.
Documente sua API
Swagger/OpenAPI, README ou pelo menos uma collection do Postman.
Separe responsabilidades
Não deixe tudo num arquivo gigante. Separe rotas, controllers, serviços e camada de acesso a dados.

Conclusão

APIs são o coração do desenvolvimento web moderno.
Se você entende:

Como definir rotas e métodos
Como enviar e receber JSON
Como trabalhar com status codes
Como separar backend (API) e frontend (consumidor)

você já está um passo na frente de muita gente.