Reading Request Data

Welcome back! In the previous lesson, you learned how to create a basic API route in Next.js and return a simple JSON response. That was a great first step. Now, let’s take things further by making your API more dynamic and interactive.

In real-world applications, APIs often need to respond differently based on the data sent by the client. This is where reading request data comes in. By learning how to read information from the request — such as query parameters in the URL — you can personalize your API’s responses and make your endpoints much more useful.

In this lesson, you will learn how to read query parameters from incoming requests and use them to customize your API’s output.

When a client (like a browser, mobile app, or frontend page) sends a request to your API, it can include data in different ways depending on the request type:

• Query Parameters (used in GET requests): These appear in the URL (like /api/user?id=123). They’re visible in the address bar and are often used for filtering or requesting specific items.
• Request Body (used in POST, PUT, or PATCH requests): This is a more private and flexible way to send data — like login forms or file uploads. The body isn’t visible in the URL and allows you to send structured data like JSON.
• Headers: These send metadata about the request, like what format you expect in the response, or which user is making the request (via tokens).

In this lesson, we’re working with GET requests, so we’ll focus on query parameters — but keep in mind that there are other ways your API can receive data depending on the method used.

The word "query" comes from the idea that you’re asking something from the server — you're making a request with specific parameters that define your "query."

Query parameters are placed in the URL after a question mark (?) and are often used with GET requests to filter, sort, or customize the response from the API. Each key-value pair is separated by an ampersand (&), like this:

/api/products?category=shoes&limit=10

In this example, category=shoes and limit=10 tell the server to only return 10 items in the "shoes" category. Query parameters are easy to use for simple input data that doesn't require authentication or large payloads.

Before we dive into reading request data, let’s quickly remind ourselves how a basic API route is set up in Next.js. Here’s a simple example, similar to what you saw in the last lesson:

// src/app/api/hello/route.ts
import { NextResponse } from 'next/server';

export async function GET() {
  return NextResponse.json({ message: "Hello, World!" });
}

This code creates a GET endpoint at /api/hello that always returns the same message. In this lesson, we’ll build on this by making the response change based on the request.

Now, let’s talk about query parameters. Query parameters are extra bits of information you can add to a URL. For example:

/api/hello?name=Jane&language=es

Here, name and language are query parameters. They allow the client to send information to your API.

In Next.js, you can use the NextRequest object to access these parameters. Let’s look at how to do this:

import { type NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  // Access the search parameters from the URL
  const searchParams = request.nextUrl.searchParams;

  // Get the 'name' and 'language' parameters
  const name = searchParams.get('name');
  const language = searchParams.get('language');
  
  return NextResponse.json({ name, language });
}

Explanation:

• request.nextUrl.searchParams is a convenience provided by Next.js. It converts the incoming request URL into a URL object automatically. It gives you access to all the query parameters in the URL.
• searchParams.get('name') tries to get the value of the name parameter. If it’s not there, it returns null.
• The same goes for language.

⚠️ Note: Parameter keys are case-sensitive. That means /api/hello?Language=es will not return the expected greeting, because 'Language' is not the same as 'language'.

Example Output:

If you visit /api/hello?name=Jane&language=es, the response will be:

{
  "name": "Jane",
  "language": "es"
}

If you visit /api/hello, the response will be:

{
  "name": null,
  "language": null
}

Now that you know how to read query parameters, let’s use them to make your API response more personal and interesting. You can use the values from the request to change the message you send back.

Here’s a more complete example, based on the outcome for this lesson:

import { type NextRequest, NextResponse } from 'next/server';

export async function GET(request: NextRequest) {
  const searchParams = request.nextUrl.searchParams;
  const name = searchParams.get('name');
  const language = searchParams.get('language') || 'en';
  const format = searchParams.get('format') || 'json';
  const timestamp = new Date().toISOString();

  // Create a greeting based on the language
  let greeting: string;
  switch (language.toLowerCase()) {
    case 'es':
      greeting = name ? `¡Hola, ${name}!` : "¡Hola, Mundo!";
      break;
    case 'fr':
      greeting = name ? `Bonjour, ${name}!` : "Bonjour, Monde!";
      break;
    case 'de':
      greeting = name ? `Hallo, ${name}!` : "Hallo, Welt!";
      break;
    default:
      greeting = name ? `Hello, ${name}!` : "Hello, World!";
  }

  // Build the response data
  const responseData = {
    message: greeting,
    timestamp: timestamp,
    parameters: {
      name: name || null,
      language: language,
      format: format
    },
    endpoint: "/api/hello",
    method: "GET",
    status: "success"
  };

  return NextResponse.json(responseData);
}

searchParams behaves like a special map of all the query parameters in the URL. It comes from the URLSearchParams interface, which provides helpful methods like:

• .get('key') – returns the value for a key (or null if not found)
• .has('key') – returns true if the key exists
• .keys() – returns all keys

You can think of it like a JavaScript Map, but for the query part of a URL. For example:

const name = searchParams.get('name'); // "Jane" if ?name=Jane
const hasFormat = searchParams.has('format'); // true or false

Internally, request.nextUrl turns the full request URL into a URL object, and .searchParams just gives you access to the part after the ?.

What’s happening here?

• We read the name, language, and format parameters from the URL.
• If language or format is missing, we use default values ('en' and 'json'). This fallback (|| 'en') ensures your API still behaves predictably even if the client doesn’t provide a language.
• We use a switch statement to choose a greeting in the right language.
• The response includes the greeting, the current time, the parameters, and some extra info.

Example Output:

If you visit /api/hello?name=Jane&language=fr, you’ll get:

{
  "message": "Bonjour, Jane!",
  "timestamp": "2024-06-01T12:34:56.789Z",
  "parameters": {
    "name": "Jane",
    "language": "fr",
    "format": "json"
  },
  "endpoint": "/api/hello",
  "method": "GET",
  "status": "success"
}

If you visit /api/hello, you’ll get:

{
  "message": "Hello, World!",
  "timestamp": "2024-06-01T12:34:56.789Z",
  "parameters": {
    "name": null,
    "language": "en",
    "format": "json"
  },
  "endpoint": "/api/hello",
  "method": "GET",
  "status": "success"
}

This makes your API much more flexible and user-friendly.

In this lesson, you learned how to read query parameters from incoming requests using the NextRequest object in Next.js. You also saw how to use these parameters to personalize your API’s response, making it more dynamic and useful.

You are now ready to practice these skills! In the next set of exercises, you’ll get hands-on experience reading request data and customizing your API responses. This is a key step in building real-world APIs, so take your time and experiment with different parameters. Good luck!