In order to turn the API Routes docs more clear about the file extensions when using `pageExtensions`. I know that it was already explained [here](https://nextjs.org/docs/api-reference/next.config.js/custom-page-extensions). But just think about the DX: If a developer have a trouble with an API endpoint not working properly should it check it on custom-page-extensions page or api-routes page itself?? Related to https://github.com/vercel/next.js/issues/8178. ## Bug - [ ] Related issues linked using `fixes #number` - [ ] Integration tests added - [ ] Errors have helpful link attached, see `contributing.md` ## Feature - [ ] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. - [ ] Related issues linked using `fixes #number` - [ ] Integration tests added - [ ] Documentation added - [ ] Telemetry added. In case of a feature if it's used or not. - [ ] Errors have helpful link attached, see `contributing.md` ## Documentation / Examples - [x] Make sure the linting passes by running `yarn lint` Co-authored-by: JJ Kasper <22380829+ijjk@users.noreply.github.com>
3.8 KiB
description |
---|
Next.js supports API Routes, which allow you to build your API without leaving your Next.js app. Learn how it works here. |
API Routes
Examples
API routes provide a solution to build your API with Next.js.
Any file inside the folder pages/api
is mapped to /api/*
and will be treated as an API endpoint instead of a page
. They are server-side only bundles and won't increase your client-side bundle size.
For example, the following API route pages/api/user.js
returns a json
response with a status code of 200
:
export default function handler(req, res) {
res.status(200).json({ name: 'John Doe' })
}
Note
: API Routes will be affected by
pageExtensions
configuration innext.config.js
.
For an API route to work, you need to export a function as default (a.k.a request handler), which then receives the following parameters:
req
: An instance of http.IncomingMessage, plus some pre-built middlewaresres
: An instance of http.ServerResponse, plus some helper functions
To handle different HTTP methods in an API route, you can use req.method
in your request handler, like so:
export default function handler(req, res) {
if (req.method === 'POST') {
// Process a POST request
} else {
// Handle any other HTTP method
}
}
To fetch API endpoints, take a look into any of the examples at the start of this section.
Use Cases
For new projects, you can build your entire API with API Routes. If you have an existing API, you do not need to forward calls to the API through an API Route. Some other use cases for API Routes are:
- Masking the URL of an external service (e.g.
/api/secret
instead ofhttps://company.com/secret-url
) - Using Environment Variables on the server to securely access external services.
Caveats
- API Routes do not specify CORS headers, meaning they are same-origin only by default. You can customize such behavior by wrapping the request handler with the CORS middleware.
- API Routes can't be used with
next export
Related
For more information on what to do next, we recommend the following sections: