API Routes no Next.js: como criar e usar na pratica

O que sao API Routes e por que elas existem

API Routes sao funcionalidades do framework Next.js que permitem criar endpoints HTTP diretamente dentro de um projeto Next.js, sem precisar montar um servidor separado. Em vez de ter um backend em Node.js, Python ou PHP rodando em outra maquina, voce cria um arquivo na pasta correta e ele ja se comporta como uma rota de API completa.

Pense da seguinte forma: normalmente, quando voce acessa um site, o navegador pede uma pagina ao servidor. Quando o site precisa conversar com um sistema (por exemplo, enviar um formulario, buscar dados em um banco, processar um pagamento), ele faz uma requisicao HTTP para um endereco especifico, e esse endereco devolve uma resposta em formato JSON. JSON e um formato leve de troca de dados, muito usado na web por ser facil de ler tanto para humanos quanto para maquinas. Cada um desses enderecos e uma API Route.

A grande vantagem e a simplicidade. Quem ja usa Next.js para construir a interface visual nao precisa aprender uma tecnologia de backend totalmente nova nem configurar servidores adicionais. Tudo fica no mesmo projeto, com o mesmo controle de versionamento em Git, o mesmo deploy e a mesma linguagem, seja ela JavaScript ou TypeScript.

Outra vantagem pratica e o deploy. Provedores como Vercel (a empresa por tras do Next.js), Netlify, AWS Amplify e Railway reconhecem automaticamente as rotas de API do Next.js e fazem o trabalho pesado de infraestrutura, incluindo escalabilidade automatica (o sistema aumenta ou diminui a capacidade conforme a demanda) e certificacao HTTPS.

Estrutura de arquivos: onde colocar cada coisa

A estrutura de arquivos muda dependendo de qual sistema de roteamento voce usa no Next.js. Existem dois: o Pages Router, mais antigo e ainda suportado, e o App Router, que se tornou o padrao a partir do Next.js 13.4 e foi refinado nas versoes 14 e 15.

Pages Router

No Pages Router, qualquer arquivo dentro da pasta pages/api/ vira automaticamente uma rota de API. A convencao e:, pages/api/usuarios.ts responde em /api/usuarios, pages/api/produto/[id].ts responde em /api/produto/123

O arquivo exporta uma funcao que recebe dois objetos: req (a requisicao) e res (a resposta). Dentro dessa funcao, voce verifica o metodo HTTP, processa os dados e devolve a resposta.

App Router

No App Router, usado por padrao em projetos novos desde 2023 e consolidado nas versoes 14 e 15, as API Routes ficam dentro da pasta app/api/. A convencao e criar uma pasta com o nome da rota e dentro dela um arquivo chamado route.ts (ou route.js se usar JavaScript puro). Exemplos:, app/api/usuarios/route.ts responde em /api/usuarios, app/api/produto/[id]/route.ts responde em /api/produto/123

O arquivo exporta funcoes nomeadas de acordo com o metodo HTTP: GET, POST, PUT, PATCH, DELETE. Isso deixa o codigo mais organizado porque cada metodo fica explicito em vez de escondido dentro de um if.

Qual escolher?

Se voce esta comecando um projeto novo em 2026, a recomendacao e usar o App Router. Ele e o futuro do Next.js, recebe as novidades primeiro e tem melhor suporte a streaming, server components e outros recursos avancados. O Pages Router ainda funciona e vai continuar sendo suportado por um bom tempo, mas nao recebe mais grandes atualizacoes.

Criando sua primeira API Route na pratica

Vamos criar um exemplo simples e funcional para voce ver como funciona na vida real. O objetivo sera uma rota que devolve uma lista de usuarios.

Exemplo com App Router (Next.js 14 ou 15)

Crie o arquivo app/api/usuarios/route.ts com o seguinte conteudo:

import { NextResponse } from 'next/server'

export async function GET() {
  const usuarios = [
    { id: 1, nome: 'Ana', email: 'ana@exemplo.com' },
    { id: 2, nome: 'Bruno', email: 'bruno@exemplo.com' },
    { id: 3, nome: 'Carla', email: 'carla@exemplo.com' },
  ]

  return NextResponse.json(usuarios)
}

Para testar, suba o projeto com npm run dev e acesse http://localhost:3000/api/usuarios no navegador. Voce vera o array de usuarios em formato JSON.

Adicionando um metodo POST

Para receber dados (por exemplo, cadastrar um novo usuario), adicione a funcao POST no mesmo arquivo:

export async function POST(request: Request) {
  const dados = await request.json()

  const novoUsuario = {
    id: Date.now(),
    nome: dados.nome,
    email: dados.email,
  }

  return NextResponse.json(novoUsuario, { status: 201 })
}

O status: 201 indica que um recurso foi criado com sucesso, seguindo o padrao HTTP. Outros status comuns sao:

• 200: requisicao bem-sucedida.
• 201: recurso criado.
• 400: erro do cliente (dados invalidos).
• 401: nao autorizado.
• 404: nao encontrado.
• 500: erro interno do servidor.

Rotas dinamicas e parametros de URL

Muitas vezes voce precisa de rotas que recebam informacoes na propria URL. Por exemplo, buscar um usuario especifico pelo ID. No App Router, isso e feito com pastas entre colchetes.

Exemplo: rota com parametro

Crie a pasta app/api/usuarios/[id]/route.ts:

import { NextResponse } from 'next/server'

export async function GET(
  request: Request,
  { params }: { params: { id: string } }
) {
  const id = params.id

  const usuario = {
    id: Number(id),
    nome: 'Usuario de exemplo',
    email: `usuario${id}@exemplo.com`,
  }

  return NextResponse.json(usuario)
}

Acessando http://localhost:3000/api/usuarios/42, voce recebera os dados daquele ID especifico.

Multiplos parametros opcionais

Se quiser deixar parametros como opcionais, use dois colchetes: [[slug]]. Tambem e possivel usar catch-all (capturar tudo que vier depois) com [...slug]. Esses recursos sao uteis para rotas mais complexas, como blogs com categorias e subcategorias aninhadas.

Trabalhando com query strings e cabecalhos

Alem dos parametros de URL, voce frequentemente precisa ler informacoes extras da requisicao, como filtros de busca, tokens de autenticacao ou cookies.

Lendo query strings

Query strings sao aqueles parametros que aparecem depois do sinal de interrogacao na URL. Por exemplo, em /api/usuarios?cidade=sao-paulo, o trecho cidade=sao-paulo e uma query string.

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const cidade = searchParams.get('cidade')
  const idadeMinima = searchParams.get('idadeMinima')

  return NextResponse.json({ cidade, idadeMinima })
}

Lendo cabecalhos e corpo da requisicao

O objeto request (no App Router) ou req (no Pages Router) da acesso a tudo isso:

• request.headers: cabecalhos HTTP.
• incluindo tokens de autenticacao, request.cookies: cookies do navegador, request.json(): corpo da requisicao em formato JSON, request.formData(): dados enviados por formularios HTML.

Boas praticas e seguranca

Criar API Routes e relativamente simples, mas existem cuidados importantes para evitar problemas em producao.

Validacao de dados

Nunca confie nos dados que chegam do cliente. Sempre valide se os campos esperados estao presentes e no formato correto. Bibliotecas populares para isso incluem:

• Zod: validacao baseada em schemas (regras que definem o formato esperado dos dados).
• Yup: alternativa mais antiga com API similar.
• Joi: bastante usada em projetos Node.js tradicionais.

Exemplo com Zod:

import { z } from 'zod'

const schemaUsuario = z.object({
  nome: z.string().min(2),
  email: z.string().email(),
})

export async function POST(request: Request) {
  const dados = await request.json()
  const validacao = schemaUsuario.safeParse(dados)

  if (!validacao.success) {
    return NextResponse.json(
      { erro: 'Dados invalidos', detalhes: validacao.error },
      { status: 400 }
    )
  }

  // Continue com a logica usando validacao.data
}

Autenticacao e autorizacao

Se a rota acessa dados sensiveis ou executa acoes importantes, voce precisa verificar quem esta fazendo a requisicao. Os metodos mais comuns em Next.js incluem:

• NextAuth.js (agora chamado Auth.js): biblioteca completa para login com Google.
• GitHub.
• email e outros provedores.
• Clerk: servico pago com painel pronto e componentes de interface prontos.
• JWT manual: implementar voce mesmo usando bibliotecas como jose ou jsonwebtoken.

Apos validar o token, armazene as informacoes do usuario em algum lugar acessivel (como o contexto da requisicao) para usar nas proximas etapas.

Rate limiting (limitacao de requisicoes)

Para evitar abusos, e recomendavel limitar quantas requisicoes um mesmo endereco IP ou usuario pode fazer em um periodo de tempo. Em producao, isso geralmente e feito com servicos externos como Upstash Redis, Cloudflare ou middleware especificos.

Cuidado com informacoes sensiveis

Nunca exponha chaves de API, segredos ou dados confidenciais nas respostas. Tambem tome cuidado com injecoes SQL (ataques em que o invasor insere comandos maliciosos em campos de formulario para manipular o banco de dados): use sempre queries parametrizadas ou ORMs. ORM significa Object-Relational Mapping, uma ferramenta que traduz objetos do codigo em comandos de banco de dados. Exemplos populares incluem Prisma, Drizzle e Sequelize.

Comparativo: quando usar API Routes e quando nao

API Routes resolvem muito bem varios cenarios, mas nao sao a melhor escolha para tudo. A tabela abaixo resume os casos mais comuns:

Middleware: logica que roda antes das rotas

O Next.js tem um recurso chamado middleware que permite executar codigo antes de uma requisicao chegar a uma rota. Isso e util para:

• Verificar autenticacao.
• Adicionar cabecalhos de seguranca (CORS.
• politica de mesma origem.
• entre outros).
• Redirecionar usuarios.
• Fazer logging (registro de acessos).

O arquivo middleware.ts fica na raiz do projeto ou em pastas especificas. Ele exporta uma funcao que decide se a requisicao continua ou e bloqueada ou redirecionada.

import { NextResponse } from 'next/server'
import type { NextRequest } from 'next/server'

export function middleware(request: NextRequest) {
  if (request.nextUrl.pathname.startsWith('/api/admin')) {
    const token = request.headers.get('authorization')

    if (!token) {
      return NextResponse.json(
        { erro: 'Acesso negado' },
        { status: 401 }
      )
    }
  }

  return NextResponse.next()
}

Casos de uso comuns no dia a dia

Para ilustrar melhor, aqui estao cenarios em que API Routes brilham:, Formulario de contato que envia e-mail usando Resend ou SendGrid, Webhook para receber pagamentos do Stripe, Mercado Pago ou PagSeguro, Endpoint que gera um PDF dinamicamente para o usuario baixar, Integracao com APIs externas (clima, cotacao de moedas, CEP), Upload de imagens que sao processadas e salvas em servicos como Cloudinary ou S3, Sincronizacao de dados entre dois sistemas, Autenticacao customizada para sistemas internos

Comparando com outras solucoes de backend

Voce pode estar se perguntando: e em relacao a outras opcoes como Express, Fastify, NestJS ou Firebase Functions? Cada uma tem seu lugar. Express: tradicional e flexivel, mas exige configuracao manual de rotas, middleware, CORS e deploy. No Next.js, tudo isso ja vem pronto. Fastify: mais rapido que o Express em benchmarks, mas com a mesma complexidade de setup. NestJS: estrutura completa para aplicacoes grandes, com injecao de dependencia e padroes de arquitetura. Pode ser overkill (complexidade desnecessaria) para a maioria dos projetos. Firebase Functions: integra bem com o ecossistema Google, mas voce fica preso ao provedor.

API Routes do Next.js ocupam um espaco interessante: dao mais estrutura que um Express puro, mas menos burocracia que um NestJS. Sao perfeitas para projetos pequenos e medios e funcionam muito bem como complemento de sistemas maiores.

Quando considerar um backend separado

Apesar das vantagens, existem situacoes em que um backend dedicado continua sendo a melhor escolha:

• Sistemas com milhares de requisicoes por segundo que exigem controle fino de performance.
• Processamento pesado.
• como geracao de videos ou analise de dados em larga escala.
• Times grandes com desenvolvedores especializados em backend.
• Necessidade de multiplos bancos de dados e fontes de dados complexas.
• Aplicacoes legadas que ja tem backend proprio e precisam de integracao.

Nesses casos, voce pode manter o Next.js apenas para a interface e consumir a API do backend separado normalmente, com fetch ou bibliotecas como axios e SWR.

Dicas para organizar o codigo

Conforme o projeto cresce, manter toda a logica dentro do arquivo route.ts pode virar bagunca. Algumas estrategias comuns:

• Separar a logica de negocio em arquivos dentro de uma pasta lib/ ou services/.
• Criar funcoes auxiliares para validacao.
• formatacao e acesso ao banco.
• Usar variaveis de ambiente (.env) para guardar chaves e configuracoes sensiveis.
• Documentar cada rota em um README interno ou comentario no inicio do arquivo.
• Adicionar testes automatizados usando Jest.
• Vitest ou ferramentas end-to-end como Cypress.

Erros comuns de iniciantes

Mesmo sendo facil de comecar, algumas armadilhas pegam muita gente:

• Esquecer de exportar a funcao com o nome correto do metodo HTTP.
• Nao tratar erros com try/catch.
• deixando a aplicacao quebrar silenciosamente.
• Colocar logica pesada dentro do handler (a funcao da rota).
• travando a resposta.
• Ignorar o tempo de execucao: em algumas plataformas.
• API Routes tem limite de duracao.
• Esquecer de configurar CORS quando o frontend esta em um dominio diferente.
• Salvar senhas em texto puro no banco (sempre use hash com bcrypt ou argon2).

Perguntas Frequentes (FAQ)

1. Preciso saber TypeScript para usar API Routes?

Nao obrigatoriamente. Voce pode escrever suas rotas em JavaScript puro, bastando usar a extensao .js em vez de .ts. Porem, TypeScript oferece seguranca extra em tempo de desenvolvimento, especialmente em projetos que manipulam muitos dados. Se voce esta comecando agora, vale o investimento de aprender o basico.

2. API Routes substituem um backend tradicional?

Para a maioria dos projetos web, sim. Porem, em sistemas muito grandes, com processamento pesado, microservicos ou regras de negocio extremamente complexas, um backend dedicado ainda faz sentido. A regra pratica: se o projeto cabe em uma unica aplicacao Next.js, API Routes resolvem. Se voce precisa dividir em varios servicos independentes, ai vale considerar outras arquiteturas.

3. Posso usar banco de dados dentro de uma API Route?

Pode e deve, sempre que precisar persistir (guardar de forma permanente) dados. Os bancos mais usados com Next.js incluem PostgreSQL (com Prisma ou Drizzle), MongoDB, Supabase, PlanetScale e Neon. A conexao com o banco deve ser feita dentro da funcao da rota ou em arquivos separados chamados pela rota.

4. Como faco deploy das API Routes?

O jeito mais simples e usar a Vercel, que reconhece automaticamente a estrutura do Next.js e faz o deploy com um unico comando ou clique. Outras opcoes incluem Netlify, AWS Amplify, Railway, Render e DigitalOcean. Em todos esses casos, o processo e mais simples do que subir um backend tradicional, porque o provedor ja entende o formato.

5. Qual a diferenca entre API Routes e Server Actions?

Server Actions, introduzidos no Next.js 13 e estabilizados nas versoes 14 e 15, sao funcoes executadas no servidor que sao chamadas diretamente de componentes React, sem precisar fazer uma requisicao HTTP manual. Sao otimos para formularios e mutacoes simples dentro do proprio app. API Routes, por outro lado, continuam sendo a melhor escolha quando voce quer expor endpoints publicos, receber webhooks de sistemas externos ou construir APIs que serao consumidas por outros aplicativos, como um app mobile ou um sistema de terceiros.

Conclusao

API Routes do Next.js sao uma das funcionalidades mais uteis do framework, especialmente para quem quer manter tudo em um unico projeto. Com poucos arquivos e algumas linhas de codigo, voce cria endpoints HTTP profissionais, com suporte a diferentes metodos, parametros dinamicos, validacao e middleware.

O segredo para usar bem essa ferramenta e entender quando ela faz sentido. Para formularios, webhooks, autenticacao e integracoes simples, ela e imbativel. Para sistemas distribuidos e processamento pesado, talvez voce precise de algo mais robusto.

O importante e comecar. Crie uma rota simples, teste no navegador, faca uma requisicao de outro lugar usando fetch ou uma ferramenta como Postman ou Insomnia, e voce vai perceber que o conceito e mais simples do que parece.

Se voce precisa de ajuda para colocar isso em pratica em um projeto real, a Baita Site tem uma equipe especializada em desenvolvimento com Next.js, integracao de APIs, e-commerce e sistemas web. Fale com a gente e veja como podemos acelerar o seu projeto.

Disclaimer

Este conteudo tem carater informativo e educacional. Decisoes de arquitetura de software devem ser tomadas considerando o contexto especifico de cada projeto, com apoio de profissionais especializados quando necessario.

Referencias consultadas, Documentacao oficial do Next.js sobre API Routes e Route Handlers

https://nextjs.org/docs/app/building-your-application/routing/route-handlers, Documentacao oficial do Next.js sobre Middleware: https://nextjs.org/docs/app/building-your-application/routing/middleware, Guia oficial de migracao do Pages Router para App Router: https://nextjs.org/docs/app/building-your-application/upgrading/app-router-migration, Repositorio oficial do Next.js no GitHub: https://github.com/vercel/next.js, Documentacao do Zod para validacao de dados: https://zod.dev, Auth.js (NextAuth) para autenticacao: https://authjs.dev, Vercel sobre deploy de aplicacoes Next.js: https://vercel.com/docs/frameworks/nextjs