How to Build a REST API with Next.js 13?

Next.js is the most widely used React framework. Next.js 13.2 introduced a new file-based routing mechanism, called App Router, for building React frontend and serverless backend. In this article, we will be building a simple REST API using Next.js Route Handlers

Prerequisites

1. Next.js 13 App Router
2. Node.js

Next.js Route Handlers

Next.js Route Handlers are used to create custom request handlers for a given route using the Web Request and Response APIs. It is replacement for API routes Pages router

Convention

Route Handlers can be defined in only route.(js | ts) files inside "app" directory which means Route Handlers are only available in App router.

You cannot define page.(js | ts) & route.(js | ts) in same route as both take over whole HTTP verbs. For example "app/login/page.ts" and "app/login/route.ts" will cause conflict.

Supported HTTP methods

Route Handlers support 7 HTTP methods which are:

1. GET
2. POST
3. PUT
4. PATCH
5. DELETE
6. HEAD
7. OPTIONS

If any method, other than these is called, Next.js will return "405 Method Not Allowed".

Caching

Only GET method is cached by default. To opt out of caching in GET requests, you can use one of the following ways:

• Using the Request(NextRequest) object.
• Using Dynamic Functions like cookies and headers.
• Use segment config options.

Don't worry, we will be going through code examples for all of them.

Segment Config Options

Settings that can be applied to layout, pages and route handlers. These include but nor limited to:

// Caching behavior
export const dynamic = 'auto'
export const dynamic = 'force-dynamic' //no-caching

//Revalidation
export const revalidate = false
export const revalidate = 60 //Revalidates every minute

//Runtime
export const runtime = 'nodejs' //default
export const runtime = 'edge'

//Vercel region
export const preferredRegion = 'auto'
export const preferredRegion = ['iad1', 'hnd1'];

NextRequest & NextResponse

NextRequest and NextRequest are extensions of Web Request and Response APIs. These have few useful methods which are not present in Web Request and Response functions.

import { NextRequest, NextResponse } from "next/server";

export async function GET(req: NextRequest) {
    const body = await req.json();
    console.log(body);
    return new NextResponse('All ok', {
        status: 200,
  });
}

Few use cases for NextRequest object include:

NextResponse shares all the methods for setting, retrieving and deleting cookies with NextRequest. There a few additional method specific to NextResponse which include:

Dynamic functions

Next.js provide dynamic functions for accessing cookies and headers in next/header library.

import { cookies, headers } from 'next/headers'

Next.js project initialization

We will be using TypeScript and pnpm for this project but you can use whatever you are comfortable with.

Step 1: Use one of the following commands to initialize the project.

#npm
npx create-next-app@latest

#yarn
yarn create next-app

#pnpm
pnpm create next-app

Choices:

Step 2: Make a data store to perform operations and retrieve information. We will not be using any database in this demo. As Next.js is a serverless backend framework, state does not persist unlike Express.js.

export const fakeUsers: TUser[] = [
    {
    id: 1,
    name: "Sarthak Roy",
    email: "sarthakroy2003@gmail.com",
    gender: "male",
    address: "Kolkata, India",
    favouriteAnime: "A Silent Voice",
    },
    {
    id: 2,
    name: "John McNormie",
    email: "john@gmail.com",
    gender: "other",
    address: "Seattle, USA",
    favouriteAnime: null,
    },
    {
    id: 3,
    name: "John Doe",
    email: "doe@gmai.com",
    gender: "male",
    address: "Springfield, USA",
    favouriteAnime: "Naruto",
    },
];

Step 4: Start the dev server.

#npm
npm run dev

#yarn
yarn dev

#pnpm
pnpm dev

package.json

"dependencies": {
    "react": "^18",
    "react-dom": "^18",
    "next": "14.2.5"
  },
  "devDependencies": {
    "typescript": "^5",
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",fallback
    "postcss": "^8",
    "tailwindcss": "^3.4.1",
    "eslint": "^8",
    "eslint-config-next": "14.2.5"
  }

Here is the code for root route. This is completely optional:

//app/page.tsx

export default function Page() {
    return (
        <main>
            <h1>Next.js API routes demo</h1>
        </main>
    )
}

Project Structure

Building REST API with Next.js Route Handlers

Get all users

As the name suggests, we will be using GET method for this operation. To get all user defile a route.ts file inside "/api/user".

//app/api/user/route.ts
import { fakeUsers } from "@/db/users";
import { NextResponse } from "next/server";

export async function GET() {

    return new NextResponse(JSON.stringify(fakeUsers), {
        status: 200,
    });
}

Now call the /api/user endpoint with GET method using Postman or Thunder Client.

Output

Get specific user

Suppose you want to specific user with id. Next.js will provides Dynamic Route Segments to do this. These are similar to dynamic routes for pages. Convention is to make for square brackets and putting a route.ts file inside it.

//app/api/user/[id]/route.ts
import { fakeUsers } from "@/db/users";
import { NextRequest, NextResponse } from "next/server";

export async function GET(
    req: NextRequest,
    { params }: { params: { id: string } }
) {
    const id = Number(params.id);
    if (isNaN(id)) {
        return new NextResponse("Invalid ID", {
            status: 400,
        });
    }

    const user = fakeUsers.find((u) => u.id === id);

    if (!user) {
        return new NextResponse("User not found", {
            status: 404,
        });
    }

    return new NextResponse(JSON.stringify(user), {
        status: 200,
    });
}

Output:

Search params

If user want to get users who have a favorite anime, we generally use search params for this.

//app/api/user/route.ts
import { fakeUsers } from "@/db/users";
import { NextRequest, NextResponse } from "next/server";

export async function GET(req: NextRequest) {
    const searchParams = req.nextUrl.searchParams;
    const hasFavoriteAnime = searchParams.get("hasFavoriteAnime");

    if (Number(hasFavoriteAnime) === 1) {
        const usersWithFavoriteAnime = fakeUsers.filter(
            (user) => user.favouriteAnime !== null
        );
        return new NextResponse(JSON.stringify(usersWithFavoriteAnime), {
            status: 200,
        });
    }

    return new NextResponse(JSON.stringify(fakeUsers), {
        status: 200,
    });
}

Output:

Create new user

We are going to create a new user using POST. In the route.ts file in 'api/user' directory, paste the following code

//app/api/user/[id]/route.ts
import { fakeUsers } from "@/db/users";
import { NextRequest, NextResponse } from "next/server";

export async function POST(req: NextRequest) {
    const body = await req.json();
    const newUser = {
        id: fakeUsers.length + 1,
        ...body,
    };
    fakeUsers.push(newUser);
    return new NextResponse(JSON.stringify(newUser), {
        status: 201,
    });
}

Output:

Change user details

Now lets use PUT method with Dynamic Route Segments to change user data.

//app/api/user/[id]/route.ts
import { fakeUsers } from "@/db/users";
import { NextRequest, NextResponse } from "next/server";

export async function PUT(
    req: NextRequest,
    { params }: { params: { id: string } }
) {
    const body = await req.json();
    const id = Number(params.id);
    if (isNaN(id)) {
        return new NextResponse("Invalid ID", {
            status: 400,
        });
    }

    const user = fakeUsers.find((u) => u.id === id);

    if (!user) {
        return new NextResponse("User not found", {
            status: 404,
        });
    }

    const updatedUser = {
        id: user.id,
        ...body,
    };

    const index = fakeUsers.indexOf(user);
    fakeUsers[index] = updatedUser;

    return new NextResponse(JSON.stringify(updatedUser), {
        status: 200,
    });
}

Output:

Delete user

We are now going to delete the user using id property.

//app/api/user/[id]/route.ts
import { fakeUsers } from "@/db/users";
import { NextRequest, NextResponse } from "next/server";

export async function DELETE(
    req: NextRequest,
    { params }: { params: { id: string } }
) {
    const id = Number(params.id);
    if (isNaN(id)) {
        return new NextResponse("Invalid ID", {
            status: 400,
        });
    }

    const user = fakeUsers.find((u) => u.id === id);

    if (!user) {
        return new NextResponse("User not found", {
            status: 404,
        });
    }

    const index = fakeUsers.indexOf(user);
    fakeUsers.splice(index, 1);

    return new NextResponse("User deleted", {
        status: 200,
    });
}

Output:

sarthakroy107

Follow

Improve