Next.js API Routes are a feature of Next.js that allows you to create server-side logic and APIs within your Next.js application. These API routes are implemented using files in the `pages/api` directory of your Next.js project. When you deploy your Next.js application, these API routes are automatically served as serverless functions.

Approach

To use Next.js API routes, create a file in the pages/api directory. Export a function to handle requests using req and res. Access the endpoint via /api/filename. Handle different methods by checking req.method.

Key points about Next.js API Routes

• File Structure: API routes are defined in individual files inside the `pages/api` directory. Each file represents a different API endpoint.
• Automatic Serverless Functions: Next.js automatically converts these API route files into serverless functions, meaning you don’t need to set up a separate server to handle API requests.
• HTTP Methods: You can define API routes for different HTTP methods like GET, POST, PUT, DELETE, etc., by creating files with corresponding names (`get.js`, `post.js`, `put.js`, etc.) inside the `pages/api` directory.
• Request Handling: Inside each API route file, you can write server-side code to handle incoming HTTP requests, process data, interact with databases or external APIs, and send back responses.
• Routing: Next.js API Routes follow a simple routing structure based on file names. For example, a `pages/api/users.js` file will create an API endpoint at `/api/users`.
• Server-Side Rendering: Since API routes run on the server side, they can access server-only functionalities and databases, making them suitable for server-side rendering (SSR) and handling sensitive operations securely.

Here’s an ;example of a simple API route in Next.js:

// pages/api/hello.js

export default function handler(req, res) {
    res.status(200).json({ message: 'Hello from the API!' });
}

In this example, visiting `/api/hello` in your Next.js application will trigger this API route, and it will respond with a JSON object containing the message “Hello from the API!”.

Dynamic API Routes

Dynamic API routes in Next.js allow you to create flexible endpoints that handle dynamic parameters in the URL. This is useful for building APIs that require variable data, such as fetching specific resources based on IDs or filtering data based on query parameters. Here’s how you can create dynamic API routes in Next.js:

• Define Dynamic Route File: Inside the `pages/api` directory, create a JavaScript file with square brackets `[]` in the filename. For example, `pages/api/users/[id].js` will create a dynamic API route that accepts `id` as a parameter.
• Access Dynamic Parameters: In the dynamic route file, export a default function (`handler`) that takes `req` (request) and `res` (response) as arguments. Inside this function, you can access dynamic parameters from the URL using `req.query` or `req.params` depending on the route structure.
• Handle Dynamic Data: Use the dynamic parameter received in the request to fetch specific data, perform operations, or customize the response based on the dynamic input.

Here’s an example of a dynamic API route in Next.js that handles a user ID parameter:

// pages/api/users/[id].js

export default function handler(req, res) {
    const { id } = req.query; // Access dynamic parameter "id"

    // Use the id to fetch user data from a database or an external API
    const userData = { id, name: 'John Doe', email: '[email protected]' };

    // Send back the user data as a JSON response
    res.status(200).json(userData);
}

In this example, visiting `/api/users/123` in your Next.js application will trigger this API route, and it will respond with a JSON object containing the user data for ID 123.

Steps to Create and Use API Routes in Next.js

Step 1: Creating an API Route

• Location: API routes reside in a dedicated folder named pages/api. Any file placed inside this folder is treated as an API endpoint.
• File Naming: The file name determines the URL path for accessing the API route. For example, a file named hello.js at pages/api/hello.js would be accessible at /api/hello.
• Function Structure: Each API route file should export a default function that takes two arguments:
• req: This is an instance of http.IncomingMessage object containing information about the incoming HTTP request (headers, body, etc.).
• res: This is an instance of http.ServerResponse object used to send the response back to the client (including status code, headers, and response data).

// api/routs.js

import { NextResponse  } from "next/server";
export async function GET() {
    return NextResponse.json({
        hello:"Geeks For Geeks",
    })
}

In this example, visiting `/api/users/123` in your Next.js application will trigger this API route, and it will respond with a JSON object containing the user data for ID 123.

Step 2: API Routes Configuration

2.1 Custom Route Paths:

By default, API routes in Next.js follow a file-based routing convention (`pages/api/`). However, you can customize the route paths using the `basePath` option in your `next.config.js` file. For example:

// next.config.js
module.exports = {
     basePath: '/api',
};

With this configuration, your API routes will be accessible under the `/api` path, such as `/api/users` instead of `/api/users.js`.

2.2 API Route Middleware:

You can add middleware functions to your API routes to handle common tasks like authentication, request validation, error handling, etc. Middleware can be applied globally or selectively to specific API routes. Here’s an example of adding middleware using the `next-connect` package:

// pages/api/users.js

import nextConnect from 'next-connect'
const middleware = (req, res, next) => {
    // Add your middleware logic here
    next()
}
const handler = nextConnect()
handler.use(middleware)
handler.get((req, res) => {
    res.status(200).json({ message: 'Hello from the API!' })
})
export default handler

2.3 Environment Variables:

You can use environment variables to configure your API routes dynamically based on different environments (development, production, testing, etc.). Next.js provides built-in support for environment variables using `.env` files. For example:

# .env.local
API_KEY=your_api_key

Then, access the environment variable in your API route like this:

// pages/api/users.js

const apiKey = process.env.API_KEY
export default function handler(req, res) {
    res.status(200).json({ apiKey })
}

2.4 API Route Caching:

You can implement caching strategies in your API routes to improve performance and reduce server load. Use caching libraries like `node-cache` or `redis` to store and retrieve cached data within your API logic.

2.5 Error Handling:

Implement robust error handling mechanisms in your API routes to gracefully handle errors, log them for debugging, and send appropriate error responses to clients. You can use try-catch blocks, error middleware, or custom error classes for this purpose.

2.6 Request Validation:

Validate incoming requests to your API routes to ensure they meet the required format, data types, and constraints. Use validation libraries like `joi`, `express-validator`, or write custom validation logic as per your application’s needs.

Step 3: Typing API Routes with TypeScript

When typing API Routes with TypeScript in Next.js, you can ensure type safety by defining types for request and response objects as well as for response data. Here’s how you can do it:

3.1 Typing Request and Response Objects:

In your API route files (`pages/api/…`), import the appropriate types from `next` to type the request and response objects.

For example, to type a GET request and response:

// pages/api/users.ts [typescript]

import { NextApiRequest, NextApiResponse } from 'next'
type Data = {
    id: number,
    name: string,
    email: string
}
export default function handler(
    req: NextApiRequest,
    res: NextApiResponse<Data>
) {
    const userData: Data = { id: 1, name: 'John Doe', email: '[email protected]' }
    res.status(200).json(userData)
}

In this example, `NextApiRequest` and `NextApiResponse<Data>` are imported from `next` and used to type the request and response objects, respectively. The `Data` type represents the structure of the response data.

3.2 Typing Response Data:

Define types for the data you expect to send in the response. This can be done using TypeScript interfaces or types.

For example, defining an interface for user data:

// types/User.ts  [typescript]

export interface User {
    id: number;
    name: string;
    email: string;
}

Then, use this interface in your API route to type the response data:

// pages/api/users.ts [typescript]

import { NextApiRequest, NextApiResponse } from 'next'
import { User } from '../../types/User'
export default function handler(
    req: NextApiRequest,
    res: NextApiResponse<User>
) {
    const userData: User = { id: 1, name: 'John Doe', email: '[email protected]' }
    res.status(200).json(userData)
}

Here, `User` is imported from the `User.ts` file in the `types` directory to type the response data.

Step 4: Accessing an API Route

You can access an API route from your frontend code (React components) using techniques like fetch or libraries like Axios. Here’s an example using fetch:

// app/page.js

'use client'
import React, { useState, useEffect } from 'react';

const HelloWorldComponent = () => {
    const [data, setData] = useState(null);

    useEffect(() => {
        fetch('/api') // Relative URL to your API route
            .then(response => response.json())
            .then(data => setData(data))
            .catch(error => console.error(
                'Error fetching data:', error));
    }, []);

    return (
        <div>
            {data ? (
                <p style={{ fontSize: '50px' }}>
                    Hello: {data.hello}
                </p>
            ) : (
                <p>Loading...</p>
            )}
        </div>
    );
};

export default HelloWorldComponent;

Output:

Output

Conclusion

In this article, we’ve looked at setting up an API route in Next.js. Next.js simplifies the process of implementing an API for your applications. It offers a couple of advantages: it does not require configuration, isolates every handler as a standalone function, has great middleware support, etc.