Rotas de API e Middleware do Next.js
Criar pontos de acesso de API sem servidor no diretório api/, processar pedidos em Route Handlers e executar Middleware na extremidade para autenticação e redirecionamentos.
Rotas de API e Middleware do Next.js é uma aula grátis de Frontend Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Frontend Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Frontend Academy inclui 4 aulas no total.
Por que usar rotas de API?
O Next.js inclui um servidor no seu aplicativo — você pode escrever endpoints de backend junto às suas páginas sem um projeto Node separado. É excelente para atuar como proxy, enviar formulários, receber webhooks e criar APIs pequenas.
Rotas de API do Roteador de Páginas
Os arquivos em pages/api/ exportam uma função padrão com req e res no estilo do Express.
// pages/api/users.ts
import type { NextApiRequest, NextApiResponse } from 'next';
export default async function handler(req: NextApiRequest, res: NextApiResponse) {
if (req.method === 'GET') {
const users = await db.users.findMany();
return res.json(users);
}
if (req.method === 'POST') {
const user = await db.users.create({ data: req.body });
return res.status(201).json(user);
}
return res.status(405).end();
}Manipuladores de rotas do Roteador de Aplicações
O Roteador de Aplicações usa a API padrão da Web de Request/Response. Cada método HTTP é uma exportação nomeada.
// app/api/users/route.ts
import { NextResponse } from 'next/server';
export async function GET() {
const users = await db.users.findMany();
return NextResponse.json(users);
}
export async function POST(request: Request) {
const body = await request.json();
const user = await db.users.create({ data: body });
return NextResponse.json(user, { status: 201 });
}Rotas de API dinâmicas
Os segmentos dinâmicos funcionam da mesma forma: app/api/users/[id]/route.ts corresponde a /api/users/123.
// app/api/users/[id]/route.ts
export async function GET(req: Request, { params }: { params: { id: string }}) {
const user = await db.users.findUnique({ where: { id: params.id }});
if (!user) return new Response('Not Found', { status: 404 });
return Response.json(user);
}Lendo cookies e cabeçalhos
No Roteador de Aplicações, use os auxiliares de next/headers (com escopo da requisição).
import { cookies, headers } from 'next/headers';
export async function GET() {
const token = cookies().get('token')?.value;
const userAgent = headers().get('user-agent');
// ...
}Respostas em fluxo
Os manipuladores de rotas podem retornar uma resposta em fluxo — útil para conclusões de conversas com IA ou para gerar arquivos grandes.
export async function GET() {
const encoder = new TextEncoder();
const stream = new ReadableStream({
async start(controller) {
for (let i = 0; i < 5; i++) {
controller.enqueue(encoder.encode(`chunk ${i}\n`));
await new Promise(r => setTimeout(r, 500));
}
controller.close();
}
});
return new Response(stream);
}Middleware — executado antes das rotas
middleware.ts, na raiz do projeto, é executado antes que as requisições cheguem às páginas ou às rotas de API. Use-o para verificações de autenticação, redirecionamentos, reescrita de cabeçalhos e testes A/B.
// middleware.ts
import { NextResponse, type NextRequest } from 'next/server';
export function middleware(request: NextRequest) {
const token = request.cookies.get('token');
if (!token && request.nextUrl.pathname.startsWith('/dashboard')) {
return NextResponse.redirect(new URL('/login', request.url));
}
return NextResponse.next();
}Correspondência do middleware
Limite os caminhos nos quais o middleware é executado com uma configuração de correspondência.
export const config = {
matcher: [
'/dashboard/:path*',
'/api/:path*',
'/((?!_next/static|_next/image|favicon.ico).*)'
]
};Ambiente de execução do middleware
O middleware é executado no Edge Runtime por padrão — um isolamento V8 leve (não é o Node completo). As APIs disponíveis são limitadas: não há módulos do Node, como fs, nem dependências nativas.
Padrão de autenticação com middleware
Uma abordagem comum é verificar um JWT no middleware, redirecionar para o login se ele estiver ausente ou inválido e anexar o usuário decodificado a um cabeçalho da requisição que as rotas subsequentes possam ler.
import jwt from 'jsonwebtoken';
export function middleware(req: NextRequest) {
const token = req.cookies.get('token')?.value;
if (!token) return NextResponse.redirect(new URL('/login', req.url));
try {
const decoded = jwt.verify(token, process.env.SECRET!);
const res = NextResponse.next();
res.headers.set('x-user-id', String(decoded.sub));
return res;
} catch {
return NextResponse.redirect(new URL('/login', req.url));
}
}Limitação de taxa no middleware
Combine o middleware com um armazenamento KV (Upstash, Vercel KV) para impor limites de taxa por IP antes de chegar à lógica da sua API.
Quando NÃO usar rotas de API
Para microsserviços separados ou APIs compartilhadas, implante um backend de verdade (Hono, Express, NestJS). As rotas de API do Next.js são excelentes para atuar como proxy, receber webhooks e criar endpoints específicos do aplicativo — não para disponibilizar uma API pública a outros clientes.
Verificação rápida
Onde o middleware do Next.js é executado e qual é o caso de uso mais comum?
Recapitulação: rotas de API e middleware
Roteador de Páginas: pages/api com req/res. Roteador de Aplicações: app/api/.../route.ts com exportações de métodos (GET/POST/etc.) usando Request/Response. Leia cookies/cabeçalhos por meio de next/headers. Respostas em fluxo com ReadableStream. middleware.ts é executado no Edge antes das rotas — autenticação, redirecionamentos e cabeçalhos. A configuração de correspondência limita os caminhos. Use um backend de verdade para APIs públicas.
Aprenda HTML com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 41
- Aulas
- 163
Perguntas Frequentes
A aula “Rotas de API e Middleware do Next.js” é grátis?
Sim — o texto completo de “Rotas de API e Middleware do Next.js” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Frontend Academy, atualize para CoddyKit PRO. O curso de Frontend Academy inclui 4 aulas no total.
O que vou aprender em “Rotas de API e Middleware do Next.js”?
Criar pontos de acesso de API sem servidor no diretório api/, processar pedidos em Route Handlers e executar Middleware na extremidade para autenticação e redirecionamentos. Você pratica Frontend Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar Frontend Academy?
Nenhuma experiência prévia é necessária. Frontend Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.
Quanto tempo leva a aula “Rotas de API e Middleware do Next.js”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de Frontend Academy?
Sim. Cada aula de Frontend Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Pages Router vs App Router
- Componentes do servidor e componentes do cliente
- SSG, SSR e ISR
- Rotas de API e Middleware do Next.js