An amazing feature of NextJS is its ability to create server APIs from within the same codebase that provides the frontend ui.

Core Concept

You can create an api in nextjs quite easily by exporting methods from a route handler module (route.ts). It integrates into the nextjs router and becomes available at a url by using the folder structure (same way as page.tsx).

An example api which supports GET is demonstrated below. It will become available at url /demo because of its filepath.

app/demo/route.ts

export async function GET() {
  return Response.json({
    message: "Hi Fam 🚀",
  });
}

Don't Mix page and route

One thing to be aware of is that you cannot have a page and a route module in the same folder.

This is because a page is nothing more than an html response to browser GET request.

As an example the page.tsx file will become invalid if we have a route.ts file in the same folder.

app/demo/page.tsx

app/demo/route.ts

export default function Page() {
  return (
    <div>
      Sample Page
    </div>
  );
}

Request Object

Just like you can use the standard Response api to generate a response, you can use the web standard Request api to read the body of incoming request. You accept the request as a parameter to the API function.

In the below example we use the .json method to parse the incoming request and then use a property from the parsed object (name) as a part of the response.

app/api/route.ts

export async function POST(request: Request) {
  const json = await request.json();
  return Response.json({
    message: `Hello ${json.name}!`,
  });
}

Methods

In addition to GET and POST, API routes within nextjs support other common http methods as well.

Complete list:

GET
POST - common to take a body payload
PUT - common to take a body payload
PATCH - common to take a body payload
DELETE
OPTIONS
HEAD - automatically supported if you provide a GET

Note that HEAD is nothing more than a GET, the only difference is that HEAD will only return the headers.

Various methods are demonstrated below.

app/api/route.ts

export async function POST(req: Request) {
  const json = await req.json();
  return Response.json({
    method: "POST",
    request: json,
  });
}

export async function PUT(req: Request) {
  const json = await req.json();
  return Response.json({
    method: "PUT",
    request: json,
  });
}

export async function PATCH(req: Request) {
  const json = await req.json();
  return Response.json({
    method: "PATCH",
    request: json,
  });
}

export async function DELETE() {
  return Response.json({
    method: "DELETE",
  });
}

export async function OPTIONS() {
  return Response.json({
    method: "OPTIONS",
  });
}

export async function GET() {
  return Response.json(
    {
      method: "GET",
    },
    {
      headers: {
        method: "GET",
      },
    }
  );
}

Method Not Allowed

A question you should have at this point is, what will happen if you call an API with a HTTP method that is not exported by our route handler?

Answer: NextJS will automatically return an error response on your behalf HTTP 405 Method Not Allowed.

As an example the below API only works on GET and POST requests and will return a 405 for other methods like PUT.

app/api/route.ts

export async function GET() {
  return Response.json({
    method: "GET",
  });
}

export async function POST(req: Request) {
  const json = await req.json();
  return Response.json({
    method: "POST",
    request: json,
  });
}

Transcript