An API route creates a server-side bundle separate from the client-side bundle. As is usual for Next.js pages, file-based routing is used to create API routes, where files inside pages/api are mapped to /api/* routes.

Apart from building the backend logic, you can use API routes to run logic that depends on a secret you don't want to expose to the client—for example, connecting to a database through a database URL string. Since API routes are server-side only, you don't have to worry about exposing the database credentials to the client.

You can also use API routes to mask external service URLs. For example, if you call https://some-service/foo, you can route it through an API route such as /api/foo to hide the actual URL used.

In this article, you'll get hands-on experience in building API routes while learning about different types of API routes in Next.js.

Implementing API Routes in Next.js

To follow this tutorial, make sure you have Node.js 14.6.0 or newer. This article uses Yarn as the package manager, but you can also use npm. If you'd like to see the code of the finished application, you can find it in this GitHub repo.

First, create a Next.js app:

Once you're prompted, choose a name for your app—for example, api-routes-demo. Select No when asked if you want to use TypeScript. You can keep the default answers to all the other questions. After the app is created, move into the app directory. You can delete the pages/api/hello.js file that was created by default.

To work with the app, you'll need some sample data. To keep things simple, you'll use a static data set, but in a real-world app, you'll likely use a database.

Create the file data.js in the project root:

Basics of API Routes

The heart of the API routes is the pages/api directory. Any file in this directory is mapped to a route of the form /api/*. So, the file pages/api/foo.js will get mapped to /api/foo. To make the API route work, you'll need to export a default function from the file, as shown below:

The function receives two arguments:

• req: An instance of http.IncomingMessage, with some pre-built middleware
• res: An instance of http.ServerResponse, with some helper functions

Before proceeding, keep these two things in mind:

1. Next.js 13 introduced a new app directory that offers an improved routing system over the traditional pages directory. However, API routes should still be defined in the pages/api directory. As this article is being written, the Next.js team hasn't decided yet how API routes will look like in the app directory. So this article will use the usual pages/api directory structure, but keep in mind it may change in the future.
2. Next.js offers a beta version of Edge API routes, which use the Edge Runtime. These API routes are often faster than their Node.js runtime counterparts but come with limitations such as not having access to native Node.js APIs. This article will not discuss Edge API routes and will only deal with standard API routes.

Static Routes

A static route is a fixed, predefined route that matches a single path verbatim. Next.js offers two equivalent ways of creating static routes. If you want a static route /api/foo, you can do one of the following:

1. Create the file foo.js in pages/api, or
2. Create the file index.js in a directory named foo in pages/api

Even though both approaches are equivalent, the second approach is much easier to work with if you have nested or dynamic routes under that particular route, as you'll see later.

Let's create two static routes—/api/users and /api/posts—and see both approaches in action. First, create a users directory in pages/api and create an index.js file in this directory with the following code:

Dynamic Routes

Fixed static routes may not be always enough for complex routing needs. For example, if you have multiple users, it's not convenient to set up individual static routes for each user, such as /api/users/1, /api/users/2, and so on. To solve this, you need to use dynamic routes, where one or more segments work as parameters that the user can pass.

For example, a route like /api/users/[id] can match /api/users/xxx, where xxx can be any valid URL component. The actual parameter passed through the URL can be accessed by the name assigned in the route (id in this example), and the appropriate record can be fetched from the database.

To create a dynamic segment, you need to add square brackets ([ ]) around the name of the file. For example, pages/api/users/[id].js will be mapped to the route /api/users/[id]. Just like in the case of static routes, you can also create a directory named [id] and create index.js inside it. Both approaches are precisely equivalent. The parameter id can be accessed in the handler function through the req.query object:

Remember that a route parameter will override a query parameter with the same name. So in the route /api/users/1?id=foo, req.query.id will be 1 and not foo.

Create a directory [id] in pages/api/users and create index.js inside it, which will map to the /api/users/[id] route. Write the following code in index.js:

Nested Routes

It's possible to create nested routes in Next.js by simply nesting directories. A directory structure like pages/api/foo/bar.js or pages/api/foo/bar/index.js will be mapped to /api/foo/bar. Let's create a posts route under /api/users/[id], which will return all posts by the specified user.

Create the file posts.js in pages/api/users/[id] with the following code:

Catch-All Routes

Catch-all routes are similar to dynamic routes, but whereas in a dynamic route, the dynamic segment matches only that particular part of the route, in a catch-all route, it matches all paths under that route. This can be created by adding three dots (...) inside the square brackets. So, a route like /api/foo/[...bar] will match /api/foo/a, /api/foo/a/b, /api/foo/a/b/c, and so on. However, it won't match /api/foo—i. e. , the path parameter cannot be omitted.

If you'd like the path parameter to be optional, you can convert it to an optional catch-all route by using two square brackets ([[ ]]). So, /api/foo/[[...bar]] matches /api/foo/a, /api/foo/a/b, /api/foo/a/b/c, and so on, as well as /api/foo. The path parameters can be accessed through req.query as before, but in this case, it will be an array of one or more elements if parameters are passed or an empty object if the parameter is omitted.

Let's create an optional catch-all route /api/comments/[[...ids]], which will do the following:

• Return all comments if no parameter is passed
• Return all comments under post xx for a route like /api/comments/xx
• Return all comments by user yy under post xx for a route like /api/comments/xx/yy

Create the directory comments in pages/api and create the file [[...ids]].js inside:

Adding JWT Authentication

If you're working on a project where your API routes should be kept private, you'll need to protect them from unauthorized access. JWT authentication is one of the most commonly used authentication mechanisms for securing APIs. You'll now add JWT authentication to the /api/users route so that the users need to log in before accessing that route.

First, stop the server if it's running. Install the required dependencies with yarn add bcryptjs jsonwebtoken. The bcrypt library is used to hash and compare the passwords, and the jsonwebtoken library is used to create and verify the JWT. Create an ENV file with the following content:

This key will be used to sign the JWT, so in an actual application, this should be a random string and kept secret.

Next, open data.js and add a password key to all the users. For simplicity, add the same password to all the users:

The value in quotes is the hashed version of the string "password".

Next, create auth.js inside pages/api. This file will log the user in and generate the token. Start with the necessary imports:

Note that you'll likely get a different token.

You can now use this token to check the authenticity of the user. Let's protect the /api/users route with JWT. Replace the content in pages/api/users/index.js with the following:

The above code checks the Authorization header for the JWT. If a token is passed, the jwt.verify function is invoked to check the token's authenticity. Once authenticated, the data is returned (with the password field stripped from the users—you wouldn't want to expose the passwords, would you?).

Test this route by passing the Authorization header to the request:

As you can see, adding JWT authentication to API routes is an involved process that can be complicated. Using something like Clerk’s Next.js authentication solution makes the process much easier since it does the heavy lifting of authentication, taking the task off your plate.

With Clerk, authentication is as simple as importing the getAuth function:

You'll learn more about authentication with Clerk in part two of this series.

Conclusion

Next.js API routes offer extreme flexibility in keeping your server-side logic close to the frontend and creating an API application. With the many different types of API routes available, it's critical to implement proper authentication to protect the routes from bad actors. However, adding authentication can be a complex and daunting task. This is why solutions like Clerk exist to make it as easy and seamless as possible.