Now, how do we add our own API routes
to a next.js application though.
For this, I got a brand new next.js project for you.
You'll find it attached to this lecture.
You can extract it, run npm install
and then once you did that,
npm run dev to start it.
But this application will now not be about our pages,
at least not the standard pages.
Indeed, there only,
is one page in that starting project
and that's a dummy homepage,
which just says "The homepage"
Now, of course we can visit this page
through local host 3000, but again,
this course module will not be
about creating pages like this.
Instead it is about this API routes feature
which is a feature built into next.js.
We can add our own API endpoints to next.js
by simply creating a new sub folder inside of pages.
So, inside of this pages directory, we create a sub folder
and that sub folder has to be called API.
Now up to this point, those file
and folder names were mostly up to you.
This is now not up to you.
This has to be called API because that's a special folder
which will be recognized by next.js
and any pages if you wanna call them like this,
which you set up inside
of that API folder will be treated in a special way.
So let's add a page inside of the API folder.
In there, you can add pages just
as you can add them anywhere else in the pages folder.
So you can pick names
of your choice index.js to handle the requests
which are just directed at /API
or to get started here, feedback.js.
Let's name it feedback.js.
So now I have that feedback.js file in the API folder
in the pages folder.
Now that will create a special path,
we can send requests to.
It will allow us to send requests to our domain.
So during development,
that's local host 3000/API/feedback.
This is what this will enable us to do.
And that should make sense
because we're in the API folder in the pages folder
and we have a feedback.js file.
Nonetheless, I mentioned that files
and folders inside of API,
so inside of this API folder would be treated
in a special way and they will,
inside of any file,
inside of the API folder,
like this feedback.js file
we don't export a react component.
So in the upper page files,
we do create a react component and export that as a default.
We don't do that in API routes.
Instead here, we create a function,
a function which we typically should name, handler
because it will handle incoming requests
and a function which will get two parameters,
a request object, which we could name, req
and a response object which we could name, res
and its dysfunction which we should export
as a default here.
Now that will not be a react component.
This is a standard Java script function.
Now because this file is in the API folder,
next.js will kind of take this function here to execute it
for incoming requests sent to /API/feedback.
And the interesting thing is that now
inside of this function,
we can not just handle get requests
and we don't have to send back HTML code.
Instead, this allows us to execute
any server side code of our choice
and that's important server side code.
Any code we write in here,
will never end up in any client side code bundle.
So any code we write here will never be exposed
to visitors of our webpage,
just as code written and getStaticProps
and getServerProps would never be exposed to our visitors.
It's the same here,
for these API routes and the code related to them.
So here in handler, for a basic start,
we could start sending back a response
and we do that with help of that response object.
Now, if you have some node.js or express.js experience,
this will look very familiar to you.
And indeed here we will write node.js code
enhanced by the next.js team to look a bit like express.js.
For example, we can send back a response
with help of the response object here.
And on that object,
we can call special methods that allow us
to send back that response and to configure that response.
For example, the status method allows us
to set a status code and that could be 200
for a start to set a success status code.
Then on that method, we can chain another method.
So call a method on the result of this first method call,
and that could be the JSON method to send back
some JSON data as part of the response
for incoming requests.
And that is quite standard.
As I mentioned before, for APIs,
you typically exchange data in that JSON format
because it's a highly machine readable
and also human readable data format,
which is the defacto standard
for exchanging data with APIs.
Now to the JSON method, we pass a JavaScript value
like an object that will then be transformed
into JSON automatically.
And here we could have a message property.
This is up to you though,
this entire object is up to you.
You can put any data you want in there
and the message could be, "This works" like this.
So by adding this line of code in that handler method
which is exported as a default,
this will be executed by next.js
when we send the request to /API/feedback
and this code will then send back a response
clearly not a page,
clearly not an HTML response
but instead some JSON data
because this response is not intended to be consumed
by entering this in the browser.
We will enter this URL in the browser
for now to start working with API routes
but that is not how we will then use them on a real page.
It's really just to get started.
So if you saved as feedback.js file now,
and I then send a request to /API/feedback,
we see our JSON our response here.
And if we open up the network tab in the dev tools
and we reload to take a closer look at that response,
we see the response data there as well.
And in the headers where we see some metadata
about that request and response,
we also see that in the response headers,
the contents type was set to application JSON.
So this is now a special kind of page
because we created that file in the special folder.
And that code now allows us to run our own server side code
and to add our own application focused API
to our overall website.
And that allows us to add features like newsletter,
signup, user feedback, submission,
maybe comment submission
or anything else you need.
And to really be able to add such features,
let's now dig a bit deeper
and explore how these API routes can be used.