Tutorial: Set Up Insomnia 5.0 for Testing Next.js 15 API Routes

Insomnia 5.0 is a powerful, open-source API client that simplifies testing REST, GraphQL, and gRPC endpoints. When working with Next.js 15, which introduces performance improvements and enhanced App Router capabilities, validating your API routes is critical to ensuring reliable application behavior. This tutorial walks you through configuring Insomnia 5.0 to test Next.js 15 API routes end-to-end, from basic GET requests to authenticated endpoints.

Prerequisites

• Node.js 18.17 or later installed (required for Next.js 15)
• Existing Next.js 15 project (or create one with npx create-next-app@latest)
• Insomnia 5.0 downloaded from the official site
• Basic understanding of REST API concepts and Next.js App Router

Step 1: Install and Launch Insomnia 5.0

After downloading the Insomnia 5.0 installer for your operating system (Windows, macOS, Linux), run the installation wizard and launch the application. On first launch:

1. Click Create a Workspace
2. Name the workspace "Next.js 15 API Testing" (or a name of your choice)
3. Select "Blank" as the workspace template, then click Create

Step 2: Set Up a Sample Next.js 15 API Route

Next.js 15 API routes live in the app/api directory under the App Router. Create a test GET endpoint to start:

1. Navigate to your Next.js project directory
2. Create the folder structure app/api/hello
3. Add a route.js file with the following code:

// app/api/hello/route.js
export async function GET() {
  return Response.json({ message: "Hello from Next.js 15 API Route" });
}

Start your Next.js dev server with npm run dev — the server will run on http://localhost:3000 by default.

Step 3: Create Your First Insomnia Request

Test the sample GET route you just created:

1. In your Insomnia workspace, click the + button next to "Requests" and select New Request
2. Name the request "GET /api/hello"
3. Set the HTTP method to GET
4. Enter the URL: http://localhost:3000/api/hello
5. Click Send

You should see a 200 OK response with the JSON body {"message": "Hello from Next.js 15 API Route"} in the response pane.

Step 4: Configure Environment Variables

Avoid hardcoding URLs by setting up environment variables in Insomnia, which makes it easy to switch between local, staging, and production environments:

1. Click the Environment button (gear icon) in the top right of the Insomnia window
2. Select Manage Environments
3. Add a new environment variable: base_url with value http://localhost:3000
4. Save the environment, then close the modal
5. Update your GET request URL to use the variable: {{base_url}}/api/hello

Send the request again to confirm it still works — Insomnia will replace the variable with the configured value automatically.

Step 5: Test POST Requests with Request Bodies

Create a POST endpoint to test sending data to your Next.js API:

1. Create the folder structure app/api/users in your Next.js project
2. Add a route.js file with the following code:

// app/api/users/route.js
export async function POST(request) {
  try {
    const body = await request.json();
    return Response.json(
      { id: Date.now(), ...body },
      { status: 201 }
    );
  } catch (error) {
    return Response.json(
      { error: "Invalid JSON body" },
      { status: 400 }
    );
  }
}

Now create a POST request in Insomnia:

1. New Request → Name: "POST /api/users", Method: POST
2. URL: {{base_url}}/api/users
3. Go to the Body tab, select JSON as the body type
4. Enter the following JSON: {"name": "Test User", "email": "[e-mail]"}
5. Click Send

You should receive a 201 Created response with the user data including the generated id field.

Step 6: Test Authenticated API Routes

Most production API routes require authentication. Let’s modify the GET /api/hello route to check for a Bearer token:

// app/api/hello/route.js (updated)
export async function GET(request) {
  const authHeader = request.headers.get("Authorization");
  if (authHeader !== "Bearer nextjs15-test-token") {
    return Response.json(
      { error: "Unauthorized" },
      { status: 401 }
    );
  }
  return Response.json({ message: "Hello Authenticated User" });
}

Add the authorization header in Insomnia:

1. Open your "GET /api/hello" request
2. Go to the Headers tab
3. Add a new header: Key: Authorization, Value: Bearer nextjs15-test-token
4. Click Send — you should see the authenticated response
5. Remove the header and send again to confirm you get a 401 Unauthorized error

Step 7: Debugging Tips for Insomnia and Next.js 15

• Check the Next.js terminal output for server-side errors if requests fail
• Use Insomnia’s Timeline tab to view full request/response details, including headers and timing
• Export your Insomnia workspace as a JSON file to share with your team (Workspace → Export)
• Use Insomnia’s Code Generation feature (right-click request → Generate Code) to get fetch or Axios snippets for your frontend
• Test edge cases like invalid JSON bodies, missing headers, and 404 routes to ensure your API handles errors properly

Conclusion

You now have Insomnia 5.0 fully configured to test all your Next.js 15 API routes, including authenticated endpoints and POST requests with bodies. Regularly testing your API routes during development will catch errors early and ensure your Next.js application is reliable. For more features, explore Insomnia’s plugin ecosystem, GraphQL testing, and automated testing capabilities.

Resources:

• Next.js 15 Route Handlers Docs
• Insomnia 5.0 Documentation