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

Last Updated : 09 Aug, 2024

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

Table of Content

Prerequisites

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:

GET
POST
PUT
PATCH
DELETE
HEAD
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:

Method	Description
request.json()	Returns a promise that resolves with the result of parsing the request body as JSON.
request.text()	Returns a promise that resolves with a text representation of the request body.
request.blob()	Returns a promise that resolves with a Blob representation of the request body.
request.nextUrl.pathname	The pathname of the URL.
request.nextUrl.searchParams	The search parameters of the URL.
request.mode	Contains the mode of request
request.cookies.set(name, value)	Given a name, set a cookie with the given value on the request.
request.cookies.get(name)	Given a name, returns the value of the cookie. If not present, return undefined.
request.cookies.getAll()	Given a cookie name, return the values of the cookie. If no name is given, return all cookies on the request.
request.cookies.delete(name)	Given a cookie name, delete the cookie from the request.
request.cookies.has(name)	Returns true if cookie exists, false if it does not
request.cookies.clear()	Clears the Set-Cookie header from the request.
request.headers.get('X-Forwarded-For')	Gets IP address of the request
request.ip	Gets IP address of the request only for Vercel hosting.

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

Method	Description
NextResponse.redirect(new URL(url, request.url))	Produce a response that redirects to a URL
NextResponse.json(body)	Produce a response with the given JSON body.
NextResponse.next()	The next() method is useful for Middleware, as it allows you to return early and continue routing.

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.

Node

export const fakeUsers: TUser[] = [     {     id: 1,     name: "Sarthak Roy",     email: "[email protected]",     gender: "male",     address: "Kolkata, India",     favouriteAnime: "A Silent Voice",     },     {     id: 2,     name: "John McNormie",     email: "[email protected]",     gender: "other",     address: "Seattle, USA",     favouriteAnime: null,     },     {     id: 3,     name: "John Doe",     email: "[email protected]",     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:

JavaScript

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

Project Structure

240723_14h04m26s_screenshot — Folder 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".

Node

//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

240723_11h40m24s_screenshot — How to Build a REST API with Next.js 13

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.

Node

//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:

240723_12h02m42s_screenshot — How to Build a REST API with Next.js 13

Search params

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

Node

//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:

240723_12h57m22s_screenshot — How to Build a REST API with Next.js 13

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

Node

//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:

240723_12h16m56s_screenshot — How to Build a REST API with Next.js 13

Change user details

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

JavaScript

//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:

240723_12h29m10s_screenshot — How to Build a REST API with Next.js 13

Delete user

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

Node

//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:

240723_12h38m37s_screenshot — How to Build a REST API with Next.js 13

Building a Task Reminder App with Next.js

sarthakroy107

Improve

Article Tags :

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

Prerequisites

Next.js Route Handlers

Convention

Supported HTTP methods

Caching

Segment Config Options

NextRequest & NextResponse

Dynamic functions

Next.js project initialization

Project Structure

Building REST API with Next.js Route Handlers

Get all users

Output

Get specific user

Search params

Create new user

Change user details

Delete user

Similar Reads