We use cookies and other tracking technologies to improve your browsing experience on our site, analyze site traffic, and understand where our audience is coming from. To find out more, please read our privacy policy.

By choosing 'I Accept', you consent to our use of cookies and other tracking technologies.

We use cookies and other tracking technologies to improve your browsing experience on our site, analyze site traffic, and understand where our audience is coming from. To find out more, please read our privacy policy.

By choosing 'I Accept', you consent to our use of cookies and other tracking technologies. Less

We use cookies and other tracking technologies... More

Login or register
to publish this job!

Login or register
to save this job!

Login or register
to save interesting jobs!

Login or register
to get access to all your job applications!

Login or register to start contributing with an article!

Login or register
to see more jobs from this company!

Login or register
to boost this post!

Show some love to the author of this blog by giving their post some rocket fuel 🚀.

Login or register to search for your ideal job!

Login or register to start working on this issue!

Login or register
to save articles!

Login to see the application

Engineers who find a new job through WorksHub average a 15% increase in salary 🚀

You will be redirected back to this page right after signin

Blog hero image

Setting up an API route with Next.js

James Calmus 18 March, 2021 | 6 min read

Over the course of my articles on Next.js, we’ve explored some of the front-end and more generic aspects of the popular framework, from setting up and using a utility-first CSS framework to getting started with testing your project.

In this article, we’re going to be focusing on the backend as we discover Next.js’s API routes.

What are Next.js API routes

At its heart, Next.js is a route-based framework for React; that’s one of the reasons it was built and what has made it so popular, because, instead of programmatically declaring the structure of your app as you do with vanilla React, you use your file structure to do it instead.

This feature can be incredibly powerful when used effectively, especially when it comes to dynamic routing and the handling of complex queries.

Building on this, and Next.js's support for server-side processing, version 9 introduced the concept of API routes. This combines Express-like RESTful endpoint creation with directory-based routing. Adding a JavaScript file into an api directory in pages creates an endpoint you can access in the browser that runs in a Node.js environment.

These routes are so simple to set up, and give you the ability to craft your own API, separate from your front-end but in the same repository.

The result is one of Next.js’s most powerful, and easy-to-use, features.

Setting up an API route

As I said, setting up these API routes is an incredibly quick affair. If you’ve created an Express endpoint before, you may also recognise some of the functions we use.

Let’s start where we left off our last project. If you need the code again, you can grab it from here - just make sure you open your terminal and install the repository's packages by running the command below:

$ yarn install

If you look at the project directory structure, you’ll see a pages folder. We know that Next.js uses the files in this folder to create our app’s route structure – i.e., the URLs that make up our app. Inside the pages folder, we have two files, our _app definition file and our homepage, index.js.

We also have a folder inside pages called api, and inside that folder, there is a single file called hello.js. Opening the file should show you an endpoint definition that looks like this:

// hello.js
// Next.js API route support: https://nextjs.org/docs/api-routes/introduction

export default (req, res) => {
  res.statusCode = 200
  res.json({ name: ‘John Doe’ })

Just as with its parent folder and creating pages for our app, every file inside api is treated as an endpoint and immediately accessible. That means if we run our app by running the following command in our terminal:

$ yarn dev

and head to http://localhost:3000/api/hello, we should see the result of our call, which looks something like this:

{ "name": "John Doe" }

So now we know our API route works, let’s go back to the endpoint’s definition in hello.js to see how it works.

Inside hello.js we can see a single, default exported function that takes two parameters, req and res, short for "request" and "response", respectively.

The default function is invoked when we visit http://localhost:3000/api/hello, and the req parameter is populated by the details of our request, such as headers, the URL we were trying to access and any query parameters contained in that URL. This is going to be useful to us later.

The res parameter allows us to access a few, Express-like functions to shape the response from our exported function. In hello.js, you can see our example API uses two of these functions, statusCode – which is fairly self-explanatory and sets the response's status code - and json - which returns a json object payload, in this case a name field set to John Doe.

If you want to see the status code function in action, head back to http://localhost:3000/api/hello in your browser, open the developer tools tab and click on Network. If you're not sure how to open your dev tools tab, take a look at this guide.

If you've never used the Network tool before, it's a great way of learning all about the requests your browser makes to display its content. Because we opened it after the network request for our API route had completed, you should see an empty list. Now refresh your browser tab.

You may see a number of requests occur, some of which could be related to any browser extensions you have installed. In amongst those requests you should see one with the name hello, which is our API route, either with a status of 200 or 304 (meaning a cached version has been returned). If you see 304, hard refresh the tab by holding the shift key while refreshing your tab to see a status code of 200.

To show how easy it is to change our API route's status code, let's head back to hello.js in the code editor.

Change line 4, to read the following:

// hello.js
res.statusCode = 404

Now head back to your browser and hard refresh the tab. In your network request list, you should see 404 listed in the Status column alongside the request titled hello. Congratulations, you've just successfully used a Next.js response object to alter your API route's status code!

Revert line 4 so our API route is returning a 200 status code again:

// hello.js
res.statusCode = 200

Now let's change the data that our API route sends back.

In hello.js, we use the json function to return "John Doe". Update that string to contain your own name. In my case, when I save the file and head back to the browser tab to refresh it, the response now shows the following:

{"name":"James Calmus"}

We've now defined an endpoint that returns a static response using Next.js.

Join our newsletter
Join over 111,000 others and get access to exclusive content, job opportunities and more!

Dynamic data and query strings in API routes

Some API routes might not take any inputs, such as the one we're currently working with. No matter when, where or with what extra parameters you call the hello API route, it will always return the same response.

There are many situations, however, where you'd like to specify some data for the API to process. For example, if you create an API route that subscribes a user to a newsletter, you'll need the user's email address to subscribe them.

The simplest way to send this data is by using a query parameter, a set of terms that follow a ? in a URL. Next.js has built-in support for query parameters, and it's incredibly easy to start consuming them.

Let's update our API to consume some query parameters that build our name.

In your browser address bar, type the following URL: http://localhost:3000/api/hello?fname=foo&lname=bar. When you press enter, the API still returns your name:

{"name":"James Calmus"}

What we want to do is to pull in the value of the variables we put into the address bar: fname and lname, and return them together as the value of name, so it reads "foo bar". To do that, we need to access that url data, which as I explained before can be accessed from the req object. Query parameters are accessible as an object via req.query.

Above line 4, add the following code:

// hello.js
const {
} = req.query;

We want to output these values to prove our API route is correctly consuming the inputs. On line 9, we need to replace our hard-coded name output with fname and lname which we can do by using a string literal:

// hello.js
res.json({ name: `${fname} ${lname}` })

If we return to the browser and refresh the tab, you should now see the following output:

{"name":"foo bar"}

This proves our API route is consuming the data we're passing through to it via query strings!


Next.js API routes are extremely useful and flexible. We've only scratched the surface of what's possible but with this knowledge, I hope you'll be able to explore API routes in more depth and start creating some really interesting endpoints.

If you'd like the code we produced in this short guide, you can find a repository here.

And if you'd like to learn more about testing Next.js API routes, I recommend Sean Connelly's blog post, Unit Testing Next.JS API Routes.

Author's avatar
James Calmus
JavaScript developer at Digital Theatre.

Related Issues

cosmos / gaia
  • Started
  • 0
  • 6
  • Intermediate
  • Go
cosmos / gaia
  • Started
  • 0
  • 3
  • Intermediate
  • Go
cosmos / ibc
  • Open
  • 0
  • 0
  • Intermediate
  • TeX

Get hired!

Sign up now and apply for roles at companies that interest you.

Engineers who find a new job through WorksHub average a 15% increase in salary.

Start with GitHubStart with Stack OverflowStart with Email