Route Handlers & Backend for Frontend

// app/api/cache/static/route.ts  -- opted in: built once, refreshed at most once a minute
export const dynamic = "force-static";
export const revalidate = 60;

export async function GET() {
  return Response.json({ generatedAt: new Date().toISOString() });
}

// app/api/cache/dynamic-default/route.ts  -- no config: runs on every request
export async function GET() {
  return Response.json({ generatedAt: new Date().toISOString() });
}

// app/api/cache/tagged/route.ts  -- a static handler whose upstream fetch carries a tag
import { BOOKSHELF_API_URL } from "@/lib/bookshelf-api";

export const dynamic = "force-static";

export async function GET() {
  const res = await fetch(`${BOOKSHELF_API_URL}/books`, { next: { tags: ["books"] } });
  return Response.json({ fetchedAt: new Date().toISOString(), books: await res.json() });
}

├ ƒ /api/cache/dynamic-default
├ ○ /api/cache/static                   1m      1y
├ ○ /api/cache/tagged

$ curl -s localhost:3604/api/cache/static; sleep 1; curl -s localhost:3604/api/cache/static
{"generatedAt":"2026-10-03T15:03:44.660Z"}
{"generatedAt":"2026-10-03T15:03:44.660Z"}

$ curl -s localhost:3604/api/cache/dynamic-default; sleep 1; curl -s localhost:3604/api/cache/dynamic-default
{"generatedAt":"2026-10-03T15:04:01.627Z"}
{"generatedAt":"2026-10-03T15:04:02.645Z"}

Error: Route segment config "dynamic" is not compatible with `nextConfig.cacheComponents`. Please remove it.

// static/route.ts -- touches nothing dynamic: prerendered at build time
export async function GET() {
  return Response.json({ projectName: "Bookshelf", version: 1 });
}

// random/route.ts -- new Date() is non-deterministic: prerendering stops, runs per request
export async function GET() {
  return Response.json({ generatedAt: new Date().toISOString() });
}

// runtime/route.ts -- a runtime API: per request
import { headers } from "next/headers";

export async function GET() {
  const userAgent = (await headers()).get("user-agent");
  return Response.json({ userAgent });
}

// cached/route.ts -- uncached data made cacheable: prerendered, refreshed on demand or by cacheLife
import { cacheLife, cacheTag } from "next/cache";
import { BOOKSHELF_API_URL } from "@/lib/bookshelf-api";

export async function GET() {
  return Response.json(await getCatalogue());
}

// "use cache" cannot go in the handler body: extract it to a helper
async function getCatalogue() {
  "use cache";
  cacheLife("hours");
  cacheTag("books");
  const res = await fetch(`${BOOKSHELF_API_URL}/books`);
  return { cachedAt: new Date().toISOString(), books: await res.json() };
}

├ ○ /api/cache/cached                  1h      1d
├ ƒ /api/cache/random
├ ƒ /api/cache/runtime
├ ○ /api/cache/static

$ curl -si localhost:3604/api/cache/static | grep -iE "cache-control|x-nextjs"
x-nextjs-cache: HIT
cache-control: s-maxage=31536000

$ curl -si localhost:3604/api/cache/cached | grep -iE "cache-control|x-nextjs"
x-nextjs-cache: HIT
cache-control: s-maxage=3600, stale-while-revalidate=82800

$ curl -s localhost:3604/api/cache/random; sleep 1; curl -s localhost:3604/api/cache/random
{"generatedAt":"2026-10-03T15:05:26.609Z"}
{"generatedAt":"2026-10-03T15:05:27.632Z"}

import Stripe from "stripe";
import { after } from "next/server";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(request: Request) {
  const signature = request.headers.get("stripe-signature");
  if (!signature) return new Response("Missing signature", { status: 400 });

  // The signature covers the exact bytes Stripe sent: read the raw text, never request.json()
  const payload = await request.text();

  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(payload, signature, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response("Invalid signature", { status: 400 });
  }

  if (event.type === "checkout.session.completed") {
    const session = event.data.object;
    // Acknowledge quickly, fulfil after the response; make the work idempotent on event.id
    after(async () => {
      console.log(`fulfil order for session ${session.id} (event ${event.id})`);
    });
  }
  return new Response(null, { status: 200 });
}

$ curl -si -X POST localhost:3604/api/webhooks/stripe -H "stripe-signature: $SIG" -d "$PAYLOAD"
HTTP/1.1 200 OK

$ curl -si -X POST localhost:3604/api/webhooks/stripe -H "stripe-signature: $SIG" -d "$TAMPERED_PAYLOAD"
HTTP/1.1 400 Bad Request
Invalid signature

$ curl -si -X POST localhost:3604/api/webhooks/stripe -d "$PAYLOAD"
HTTP/1.1 400 Bad Request
Missing signature

# server log, after the first request only:
fulfil order for session cs_test_1 (event evt_test_1)

import { revalidateTag } from "next/cache";
import { type NextRequest, NextResponse } from "next/server";
import { timingSafeEqual } from "node:crypto";

function sameSecret(received: string | null, expected: string | undefined) {
  if (!received || !expected) return false;
  const a = Buffer.from(received);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

export async function POST(request: NextRequest) {
  if (!sameSecret(request.headers.get("x-webhook-secret"), process.env.REVALIDATE_SECRET_TOKEN)) {
    return NextResponse.json({ success: false }, { status: 401 });
  }
  const { tag } = (await request.json().catch(() => ({}))) as { tag?: string };
  if (!tag) return NextResponse.json({ success: false }, { status: 400 });
  revalidateTag(tag, "max");
  return NextResponse.json({ success: true, revalidated: tag });
}

$ curl -si -X POST localhost:3604/api/webhooks/cms -H 'content-type: application/json' -d '{"tag":"books"}'
HTTP/1.1 401 Unauthorized
{"success":false}

$ curl -s -X POST localhost:3604/api/webhooks/cms -H 'x-webhook-secret: <the placeholder secret>' \
    -H 'content-type: application/json' -d '{"tag":"books"}'
{"success":true,"revalidated":"books"}

import "server-only";

// The only module that knows where the Bookshelf API lives (FastAPI, NestJS or Django)
export const BOOKSHELF_API_URL = process.env.BOOKSHELF_API_URL ?? "http://127.0.0.1:8000";

import { type NextRequest, NextResponse } from "next/server";
import { cookies } from "next/headers";
import { BOOKSHELF_API_URL } from "@/lib/bookshelf-api";

// Which upstream paths the browser may reach, and with which methods
const ROUTES: { pattern: RegExp; methods: ReadonlySet<string> }[] = [
  { pattern: /^books$/, methods: new Set(["GET", "POST"]) },
  { pattern: /^books\/events$/, methods: new Set(["GET"]) },
  { pattern: /^books\/\d{1,9}$/, methods: new Set(["GET"]) },
  { pattern: /^books\/\d{1,9}\/reviews$/, methods: new Set(["GET"]) },
];

async function proxy(request: NextRequest, ctx: RouteContext<"/api/bff/[...path]">) {
  const { path } = await ctx.params;
  const relative = path.join("/");

  const route = ROUTES.find((r) => r.pattern.test(relative));
  if (!route) return NextResponse.json({ error: "Not found" }, { status: 404 });
  if (!route.methods.has(request.method)) {
    return NextResponse.json(
      { error: "Method not allowed" },
      { status: 405, headers: { Allow: [...route.methods].join(", ") } },
    );
  }

  // The base is fixed; the user only chooses a validated path and a query string.
  // Resolve a *relative* path against a base that ends in "/", so a base with a path
  // prefix (https://api.example/v1) keeps it: .../v1/books, not .../books.
  const base = BOOKSHELF_API_URL.endsWith("/") ? BOOKSHELF_API_URL : `${BOOKSHELF_API_URL}/`;
  const upstreamUrl = new URL(relative, base);
  upstreamUrl.search = request.nextUrl.search;

  // Build the outgoing headers from scratch (allow-list); the token lives in an httpOnly cookie
  const headers = new Headers({ Accept: "application/json" });
  const contentType = request.headers.get("content-type");
  if (contentType) headers.set("Content-Type", contentType);
  const token = (await cookies()).get("bookshelf_token")?.value;
  if (token) headers.set("Authorization", `Bearer ${token}`);

  const upstream = await fetch(upstreamUrl, {
    method: request.method,
    headers,
    body: request.method === "GET" ? undefined : await request.text(),
    redirect: "manual",
    signal: AbortSignal.timeout(5_000),
  }).catch(() => null);
  if (!upstream) return NextResponse.json({ error: "Upstream unavailable" }, { status: 502 });

  // Return only what the browser needs; never copy Set-Cookie or internal headers
  return new Response(upstream.body, {
    status: upstream.status,
    headers: {
      "Content-Type": upstream.headers.get("content-type") ?? "application/json",
      "Cache-Control": "private, no-store",
    },
  });
}

export { proxy as GET, proxy as POST };

$ curl -s "localhost:3604/api/bff/books?q=sol"
[{"id":3,"title":"Solaris","author":"Stanislaw Lem"}]

$ curl -si localhost:3604/api/bff/admin/users | sed -n '1p;$p'
HTTP/1.1 404 Not Found
{"error":"Not found"}

$ curl -si "localhost:3604/api/bff/books/..%2Fadmin%2Fusers" | sed -n '1p;$p'
HTTP/1.1 404 Not Found
{"error":"Not found"}

$ curl -si -X POST localhost:3604/api/bff/books/2 | sed -n '1p;$p'
HTTP/1.1 405 Method Not Allowed
{"error":"Method not allowed"}

$ curl -si -X POST localhost:3604/api/bff/books -H 'content-type: application/json' -d '{"title":"X","author":"Y"}'
HTTP/1.1 401 Unauthorized
{"detail":"Not authenticated"}

$ curl -si -X POST localhost:3604/api/bff/books -H 'Cookie: bookshelf_token=demo-token' \
    -H 'content-type: application/json' -d '{"title":"X","author":"Y"}'
HTTP/1.1 201 Created
{"id":4,"title":"X","author":"Y"}

$ curl -sN localhost:3604/api/bff/books/events
data: {"n":1}      (about 300 ms apart)
data: {"n":2}
data: {"n":3}

{"method":"POST","path":"/books","headers":{"host":"127.0.0.1:36040","accept":"application/json","content-type":"application/json","authorization":"Bearer demo-token","user-agent":"node","content-length":"26"}}

import { BOOKSHELF_API_URL } from "@/lib/bookshelf-api";

// ANTI-PATTERN: forwards whatever path and headers the caller sends
export async function GET(request: Request, ctx: { params: Promise<{ path: string[] }> }) {
  const { path } = await ctx.params;
  const upstream = await fetch(`${BOOKSHELF_API_URL}/${path.join("/")}`, { headers: request.headers });
  return new Response(upstream.body, { status: upstream.status, headers: upstream.headers });
}

# an internal-only endpoint the browser was never meant to reach
$ curl -s localhost:3604/api/unsafe/admin/users
[{"id":1,"email":"internal-only@example.test"}]

# the caller's own Authorization header is forwarded as if it were the server's, and the
# upstream Set-Cookie is handed back to the browser
$ curl -si localhost:3604/api/unsafe/books/1 -H 'Authorization: Bearer leaked' | grep -iE "^HTTP|set-cookie"
HTTP/1.1 200 OK
set-cookie: upstream_session=1; Path=/

import { BOOKSHELF_API_URL } from "@/lib/bookshelf-api";

export async function GET(_request: Request, ctx: RouteContext<"/api/bff-aggregate/[id]">) {
  const { id } = await ctx.params;
  if (!/^\d{1,9}$/.test(id)) return Response.json({ error: "Invalid id" }, { status: 400 });

  const [bookRes, reviewsRes] = await Promise.all([
    fetch(`${BOOKSHELF_API_URL}/books/${id}`, { signal: AbortSignal.timeout(5_000) }),
    fetch(`${BOOKSHELF_API_URL}/books/${id}/reviews`, { signal: AbortSignal.timeout(5_000) }),
  ]);
  if (bookRes.status === 404) return Response.json({ error: "Book not found" }, { status: 404 });
  if (!bookRes.ok || !reviewsRes.ok) return Response.json({ error: "Upstream error" }, { status: 502 });

  const book = (await bookRes.json()) as { id: number; title: string; author: string };
  const reviews = (await reviewsRes.json()) as { rating: number }[];
  const average = reviews.length ? reviews.reduce((sum, r) => sum + r.rating, 0) / reviews.length : null;
  // One round trip for the browser, only the fields the UI uses
  return Response.json({ id: book.id, title: book.title, author: book.author, reviewCount: reviews.length, average });
}

$ curl -s localhost:3604/api/bff-aggregate/1
{"id":1,"title":"Dune","author":"Frank Herbert","reviewCount":1,"average":5}

$ curl -si localhost:3604/api/bff-aggregate/99 | sed -n '1p;$p'
HTTP/1.1 404 Not Found
{"error":"Book not found"}

$ curl -si localhost:3604/api/bff-aggregate/1abc | sed -n '1p;$p'
HTTP/1.1 400 Bad Request
{"error":"Invalid id"}

Error occurred prerendering page "/selffetch". Read more: https://nextjs.org/docs/messages/prerender-error
[TypeError: fetch failed] { [cause]: AggregateError: { code: 'ECONNREFUSED' } }
Export encountered an error on /selffetch/page: /selffetch, exiting the build.