Middleware for API routes in NextJS - Step-by-Step Execution

Concept Flow - Middleware for API routes

API Request Received

↓

Middleware Runs First

↓

Middleware Passes

↓

API Route Handler

↓

Response Sent Back

When an API request comes in, middleware runs first to check or modify the request. If it passes, the API handler runs; if blocked, an error response is sent.

Execution Sample

NextJS

export function middleware(req) {
  if (!req.headers.get('authorization')) {
    return new Response('Unauthorized', { status: 401 });
  }
}

export async function GET(req) {
  return new Response('Success');
}

This middleware checks for an authorization header before allowing the GET API route to respond.

Execution Table

Step	Action	Request Headers	Middleware Result	API Handler Called	Response Sent
1	Request received with no authorization header	{}	Returns 401 Unauthorized	No	401 Unauthorized
2	Request received with authorization header	{authorization: 'token123'}	Passes middleware	Yes	200 Success
3	Request received with empty authorization header	{authorization: ''}	Passes middleware (header exists)	Yes	200 Success
4	Request received with other headers	{content-type: 'json'}	Returns 401 Unauthorized	No	401 Unauthorized

💡 Middleware blocks requests missing 'authorization' header, stopping API handler from running.

Variable Tracker

Variable	Start	After Step 1	After Step 2	After Step 3	After Step 4
req.headers.get('authorization')	undefined	undefined	'token123'	''	undefined
middleware result	none	Response 401	pass	pass	Response 401
API handler called	no	no	yes	yes	no
response status	none	401	200	200	401

Key Moments - 3 Insights

Why does the API handler not run when the authorization header is missing?

Because the middleware returns a 401 Response early (see execution_table step 1), it stops further processing and the API handler is never called.

If the authorization header is empty, why does the middleware pass?

The middleware only checks if the header exists, not its content. An empty string counts as existing, so it passes (execution_table step 3).

What happens if middleware returns a Response object?

Returning a Response from middleware stops the API handler from running and sends that response immediately (see steps 1 and 4).

Visual Quiz - 3 Questions

Look at the execution table, what is the middleware result at step 2?

A Returns 401 Unauthorized

B Passes middleware

C Throws an error

D Skips middleware

💡 Hint

Check the 'Middleware Result' column at step 2 in the execution_table.

At which step does the API handler NOT get called?

A Step 1

B Step 3

C Step 2

D Step 3 and 4

💡 Hint

Look at the 'API Handler Called' column for each step in the execution_table.

If the middleware checked for a specific token value instead of just existence, how would step 3 change?

A API handler would not be called

B Middleware would still pass

C Middleware would return 401 Unauthorized

D Response would be 500 error

💡 Hint

Think about how checking token value affects middleware result in step 3's empty string header.

Concept Snapshot

Middleware runs before API routes in Next.js.
It can block or modify requests.
Return a Response in middleware to stop API handler.
Check headers or auth in middleware.
If middleware passes, API route runs normally.

Full Transcript

In Next.js API routes, middleware runs first when a request arrives. It can check things like headers or authorization. If middleware returns a Response, it stops the API handler from running and sends that response immediately. If middleware does not return a Response, the API handler runs and sends its response. For example, middleware can check if an authorization header exists. If missing, it returns a 401 Unauthorized response. If present, the API handler runs and returns success. This flow helps protect API routes by filtering requests early.

Practice

1. What is the main purpose of middleware in Next.js API routes?

easy

A. To run code before the API route handles a request

B. To replace the API route handler completely

C. To style the API response

D. To store data permanently on the server

Solution

1. Step 1: Understand middleware role

   Middleware runs before the API route handler to process requests.

2. Step 2: Identify correct purpose

   It can check, block, or modify requests but does not replace handlers or style responses.

3. Final Answer:

   To run code before the API route handles a request -> Option A

4. Quick Check:

   Middleware runs before API handler [OK]

Hint: Middleware runs before API handler to control requests [OK]

Common Mistakes:

• Thinking middleware replaces the API handler
• Confusing middleware with styling or storage
• Assuming middleware runs after the API handler

2. Which of the following is the correct way to continue to the API route handler inside Next.js middleware?

easy

A. return NextResponse.stop()

B. return NextResponse.redirect()

C. return NextResponse.next()

D. return NextResponse.error()

Solution

1. Step 1: Recall Next.js middleware continuation method

   To continue processing the request, middleware must call NextResponse.next().

2. Step 2: Match correct method

   NextResponse.stop() halts, redirect() sends elsewhere, error() signals failure.

3. Final Answer:

   return NextResponse.next() -> Option C

4. Quick Check:

   Use NextResponse.next() to continue [OK]

Hint: Use NextResponse.next() to proceed to API handler [OK]

Common Mistakes:

• Using NextResponse.stop() which blocks the request
• Confusing redirect() with continuing
• Forgetting to return NextResponse.next()

3. Given this middleware code, what will happen when a request with header x-auth: secret is sent?

import { NextResponse } from 'next/server';

export function middleware(request) {
  if (request.headers.get('x-auth') !== 'secret') {
    return NextResponse.redirect(new URL('/unauthorized', request.url));
  }
  return NextResponse.next();
}

medium

A. The request is redirected to /unauthorized

B. The request continues to the API route handler

C. The middleware throws an error

D. The request is blocked with no response

Solution

1. Step 1: Check header condition

   The middleware checks if 'x-auth' header equals 'secret'. If yes, it continues.

2. Step 2: Analyze given header

   The request has 'x-auth: secret', so condition is false and middleware returns NextResponse.next().

3. Final Answer:

   The request continues to the API route handler -> Option B

4. Quick Check:

   Header matches 'secret' so continue [OK]

Hint: Check header value to decide redirect or continue [OK]

Common Mistakes:

• Assuming redirect happens even if header matches
• Thinking middleware throws error on mismatch
• Ignoring header case sensitivity

4. Identify the error in this Next.js middleware code:

import { NextResponse } from 'next/server';

export function middleware(request) {
  if (!request.headers.get('authorization')) {
    NextResponse.redirect('/login');
  }
  return NextResponse.next();
}

medium

A. Using 'authorization' header instead of 'auth'

B. Middleware function must be async

C. NextResponse.next() should be inside the if block

D. Missing return before NextResponse.redirect

Solution

1. Step 1: Check redirect usage

   NextResponse.redirect must be returned to stop further processing.

2. Step 2: Identify missing return

   The code calls NextResponse.redirect but does not return it, so middleware continues incorrectly.

3. Final Answer:

   Missing return before NextResponse.redirect -> Option D

4. Quick Check:

   Always return redirect response [OK]

Hint: Always return redirect to stop middleware flow [OK]

Common Mistakes:

• Not returning redirect response
• Thinking middleware must be async
• Misplacing NextResponse.next() inside if block

5. You want to create middleware that blocks requests to API routes if the query parameter token is missing or empty. Which code correctly implements this behavior?

hard

A. export function middleware(request) {
const url = new URL(request.url);
if (!url.searchParams.get('token')) {
return NextResponse.redirect(new URL('/error', request.url));
}
return NextResponse.next();
}

B. export function middleware(request) {
if (!request.query.token) {
return NextResponse.redirect('/error');
}
return NextResponse.next();
}

C. export function middleware(request) {
if (request.url.token === '') {
return NextResponse.next();
}
return NextResponse.redirect('/error');
}

D. export function middleware(request) {
const token = request.headers.get('token');
if (!token) {
return NextResponse.next();
}
return NextResponse.redirect('/error');
}

Solution

1. Step 1: Access query parameters correctly

   Use new URL(request.url) and url.searchParams.get('token') to read query params.

2. Step 2: Check token presence and redirect if missing

   If token is missing or empty, redirect to /error; otherwise continue with NextResponse.next().

3. Final Answer:

   Code that checks query param and redirects if missing -> Option A

4. Quick Check:

   Use URL and searchParams for query checks [OK]

Hint: Use URL and searchParams to check query tokens [OK]

Common Mistakes:

• Trying to access query params directly on request
• Checking headers instead of query parameters
• Reversing redirect and continue logic