Your First API Endpoint

Welcome to your first lesson in backend development with Next.js! In this course, you will learn how to build the backend part of a web application using Next.js API routes.

Let’s start with a simple question: What is an API endpoint?
An API endpoint is a specific URL on your server that can receive requests and send back responses. Think of it as a door to your application’s data or features. For example, when you visit a website and see a list of products, your browser is often talking to an API endpoint behind the scenes to get that data.

In this lesson, you will create your very first API endpoint using Next.js. This is a key skill for building modern web applications, and it will be the foundation for everything else you do in this course.

Before we dive into more details, let’s take a moment to understand what Next.js is and why we’re using it. Next.js is a full-stack React framework that lets you build modern web applications with server-side capabilities built right in. It's developed by Vercel and built on top of React and Node.js.

You might wonder:

“Why not just use React alone or something like Express.js for the backend?”

Here’s the difference:

• React handles only the frontend — it's used to build user interfaces but doesn’t know how to talk to databases or handle server logic.
• Express.js is a popular backend framework, but it requires more manual setup and isn’t integrated with React out of the box.
• Next.js, on the other hand, combines both worlds. It gives you:
  • A powerful frontend framework (React),
  • Built-in routing,
  • Server-side rendering,
  • And full support for API routes, which let you write backend code right inside your project.

This makes it easier and faster to build full-stack apps without needing separate projects for frontend and backend. You can handle everything in one codebase.

In this course, we focus on the backend capabilities of Next.js — starting with API routes — so you’ll see how you can respond to requests, build server-side logic, and eventually integrate with databases and frontend pages.

Before we jump in, let’s quickly review where API routes live in a Next.js project. In Next.js with the App Router, API routes live inside the app/api directory. Each folder inside app/api becomes part of the URL path, and must contain a route.ts or route.js file that defines the API logic for that endpoint.

Here’s a quick overview of where you’ll be working:

src/
  app/
    api/
      hello/
        route.ts   <-- This is where your new API route will go

You don’t need to worry about setting up this structure on CodeSignal, as it’s already prepared for you. On your own computer, you would create these folders and files yourself.

Keep in mind that the folder name inside app/api becomes part of the URL path. So if you create a file at app/api/hello/route.ts, it becomes available at /api/hello route. Also, the filename must be route.ts (or route.js) when using the App Router — this is a convention required by the framework.

Let’s build your first API endpoint! You will create a file called route.ts inside the src/app/api/hello/ folder. This file will handle requests to /api/hello.

Here’s the code you’ll use:

import { NextResponse } from 'next/server';

/**
 * Handles GET requests to /api/hello.
 * This is a basic API endpoint that demonstrates the fundamental structure
 * of Next.js API routes using the App Router.
 * @param {Request} request - The incoming request object.
 * @returns {NextResponse} A JSON response with a welcome message.
 */
export async function GET(request: Request) {
  // Get the current timestamp to include in the response
  const timestamp = new Date().toISOString();
  
  // Create a response object with multiple pieces of information
  const responseData = {
    message: "Hello, World!",
    timestamp: timestamp,
    endpoint: "/api/hello",
    method: "GET",
    status: "success"
  };

  // Log the request for debugging purposes
  console.log(`GET request received at /api/hello at ${timestamp}`);

  // The NextResponse object extends the standard Response object
  // with helpers for convenience, like .json().
  // We return a standard JSON payload with a 200 OK status code.
  return NextResponse.json(responseData);
}

Let’s break down what’s happening here:

• import { NextResponse } from 'next/server';
NextResponse is a special utility provided by Next.js that extends the standard Response object from the browser Fetch API. It includes helpers like .json() for easier response formatting. You could also use the native Response object, but NextResponse simplifies common tasks and integrates better with Next.js features like middleware and routing.

• export async function GET(request: Request) { ... }
  This function will run whenever someone sends a GET request to /api/hello. In web development, GET is the most common way to ask for data. Next.js automatically maps this GET function to the HTTP GET method for the /api/hello route. If you wanted to handle other request types like POST or DELETE, you would export other functions like POST() or DELETE() from the same file. We'll cover this in more details in the next units.

• Inside the function:

  • We get the current time with new Date().toISOString(). Using .toISOString() ensures the timestamp is in a standard format (ISO 8601) that’s easy to parse, compare, or store in databases.
  • We build a response object with a message, timestamp, endpoint, method, and status.
  • We log the request to the console for debugging.
  • We return the response as JSON using NextResponse.json(responseData). This converts your object to a JSON string, ensuring that the client (like your browser or a frontend app) knows how to parse the response correctly.

When you visit /api/hello in your browser or send a GET request, you’ll get a response like this:

{
  "message": "Hello, World!",
  "timestamp": "2024-06-01T12:34:56.789Z",
  "endpoint": "/api/hello",
  "method": "GET",
  "status": "success"
}

You might notice that the response includes more than just a simple message. Here’s why each part is useful:

• message: A friendly greeting to show the endpoint is working.
• timestamp: The exact time the request was handled. This is helpful for debugging and tracking.
• endpoint: Shows which endpoint was called. This is useful if you have many endpoints.
• method: Tells you what kind of request was made (GET, POST, etc.).
• status: A simple way to show if the request was successful.

Also, the line with console.log(...) writes a message to your server’s console every time the endpoint is called. This is a basic but powerful way to see what’s happening in your application as you build and test it.

In this lesson, you learned what an API endpoint is and how to create your first one in Next.js. You saw how to:

• Place your API route in the correct folder.
• Write a handler for GET requests.
• Build and return a JSON response with useful information.
• Use console.log for simple debugging.

Now that you’ve seen how it works, you’ll get a chance to practice by creating and testing your own API endpoints in the next exercises. This hands-on practice will help you get comfortable with the basics before moving on to more advanced topics. Good luck, and have fun building!