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:

  1. export default function handler(req, res) {
  2. res.status(200).json({ name: 'John Doe' })
  3. }

Note: API Routes will be affected by pageExtensions configuration in next.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:

To handle different HTTP methods in an API route, you can use req.method in your request handler, like so:

  1. export default function handler(req, res) {
  2. if (req.method === 'POST') {
  3. // Process a POST request
  4. } else {
  5. // Handle any other HTTP method
  6. }
  7. }

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 of https://company.com/secret-url)
  • Using Environment Variables on the server to securely access external services.

Caveats

For more information on what to do next, we recommend the following sections:

API Routes Request Helperslearn about the built-in helpers for the request.

Response Helperslearn about the built-in methods for the response.

TypeScriptAdd TypeScript to your API Routes.