Rutas de API y middleware de Next.js
Cree endpoints de API sin servidor en el directorio api/, procese solicitudes en Route Handlers y ejecute Middleware en el edge para la autenticación y las redirecciones.
Rutas de API y middleware de Next.js es una lección gratuita de Frontend Academy en CoddyKit. Esta es la lección 4 de 4. Puedes leer la lección completa abajo gratuitamente — luego la practicas en el navegador con un editor de código integrado y un tutor de IA 24/7. Forma parte de la ruta de aprendizaje de Frontend Academy, y tu progreso se sincroniza en la web y la app de CoddyKit. El curso de Frontend Academy incluye 4 lecciones en total.
¿Por qué usar API Routes?
Next.js incluye un servidor con su aplicación: puede escribir endpoints de backend junto a sus páginas sin crear un proyecto de Node independiente. Es ideal para actuar como proxy, enviar formularios, recibir webhooks y crear API pequeñas.
Rutas de API de Pages Router
Los archivos de pages/api/ exportan una función predeterminada con (req, res) al estilo de 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();
}Manejadores de rutas de App Router
App Router utiliza la API estándar de Web Request/Response. Cada método HTTP es una exportación con nombre.
// 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 });
}Rutas de API dinámicas
Los segmentos dinámicos funcionan de la misma manera: app/api/users/[id]/route.ts coincide con /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);
}Leer cookies y encabezados
En App Router, utilice las funciones auxiliares de next/headers, cuyo ámbito corresponde a la solicitud.
import { cookies, headers } from 'next/headers';
export async function GET() {
const token = cookies().get('token')?.value;
const userAgent = headers().get('user-agent');
// ...
}Respuestas en streaming
Los manejadores de rutas pueden devolver una respuesta en streaming, lo que resulta útil para completar chats de IA o generar archivos 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 — Se ejecuta antes de las rutas
middleware.ts, ubicado en la raíz del proyecto, se ejecuta antes de que las solicitudes lleguen a las páginas o a las rutas de API. Utilícelo para comprobaciones de autenticación, redirecciones, reescritura de encabezados y pruebas 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();
}Matcher de Middleware
Limite las rutas en las que se ejecuta el middleware mediante una configuración de matcher.
export const config = {
matcher: [
'/dashboard/:path*',
'/api/:path*',
'/((?!_next/static|_next/image|favicon.ico).*)'
]
};Entorno de ejecución del Middleware
El middleware se ejecuta de forma predeterminada en Edge Runtime, un aislamiento ligero de V8, no en Node completo. Las API disponibles son limitadas: no se admiten módulos de Node como fs ni dependencias nativas.
Patrón de autenticación con Middleware
Un patrón habitual es verificar un JWT en el middleware, redirigir al inicio de sesión si falta o no es válido y adjuntar el usuario descodificado a un encabezado de la solicitud que las rutas posteriores puedan leer.
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));
}
}Limitación de velocidad en Middleware
Combine el middleware con un almacén KV (Upstash, Vercel KV) para aplicar límites de solicitudes por IP antes de ejecutar la lógica de su API.
Cuándo NO usar API Routes
Para microservicios independientes o API compartidas, implemente un backend real (Hono, Express, NestJS). Las rutas de API de Next.js son ideales para actuar como proxy, recibir webhooks y gestionar endpoints específicos de la aplicación, no para ofrecer una API pública a otros clientes.
Comprobación rápida
¿Dónde se ejecuta el middleware de Next.js y cuál es el caso de uso más habitual?
Resumen: API Routes y Middleware
Pages Router: pages/api con req/res. App Router: app/api/.../route.ts con exportaciones de métodos (GET/POST/etc.) que utilizan Request/Response. Lea cookies y encabezados mediante next/headers. Utilice ReadableStream para respuestas en streaming. middleware.ts se ejecuta en Edge antes de las rutas, para autenticación, redirecciones y encabezados. La configuración de matcher limita las rutas. Utilice un backend real para las API públicas.
Aprende HTML con un tutor de IA — gratis
Escribe y ejecuta código real en tu navegador, obtén ayuda instantánea de un tutor de IA disponible 24/7 y continúa donde lo dejaste en la web o en la aplicación.
- Cursos
- 41
- Lecciones
- 163
Preguntas frecuentes
¿La lección «Rutas de API y middleware de Next.js» es gratis?
Sí — el texto completo de «Rutas de API y middleware de Next.js» es gratis para leer aquí en la web. Para practicarla de forma interactiva (editor de código integrado y tutor de IA 24/7) y desbloquear el resto del curso de Frontend Academy, actualiza a CoddyKit PRO. El curso de Frontend Academy incluye 4 lecciones en total.
¿Qué aprenderé en «Rutas de API y middleware de Next.js»?
Cree endpoints de API sin servidor en el directorio api/, procese solicitudes en Route Handlers y ejecute Middleware en el edge para la autenticación y las redirecciones. Practicas Frontend Academy con código real que ejecutas directamente en el navegador, y un tutor de IA 24/7 responde tus preguntas mientras trabajas en la lección.
¿Necesito experiencia previa para empezar Frontend Academy?
No se requiere experiencia previa. Frontend Academy en CoddyKit está estructurado para principiantes hasta estudiantes avanzados, así que puedes empezar aquí o desde el inicio y avanzar a tu ritmo. Esta es la lección 4 de 4.
¿Cuánto tiempo toma la lección «Rutas de API y middleware de Next.js»?
La mayoría de las lecciones de CoddyKit toman alrededor de 5–10 minutos. Cada una es compacta e interactiva, así que avanzas constantemente y retomas exactamente por donde dejaste en la web y la app.
¿Puedo escribir y ejecutar código en esta lección de Frontend Academy?
Sí. Cada lección de Frontend Academy incluye un editor de código integrado, así que escribes y ejecutas código real directamente en tu navegador y obtienes retroalimentación instantánea de IA — sin configuración local necesaria.
Todas las lecciones de este curso
- Pages Router frente a App Router
- Componentes de servidor y componentes de cliente
- SSG, SSR e ISR
- Rutas de API y middleware de Next.js