API Routes

Examples

• Basic API Routes
• API Routes with middleware
• API Routes with GraphQL
• API Routes with REST
• API Routes with CORS

API routes provide a straightforward 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 handles a json response:

export default function handler(req, res) {
  res.statusCode = 200
  res.setHeader('Content-Type', 'application/json')
  res.end(JSON.stringify({ name: 'John Doe' }))
}

For an API route to work, you need to export as default a function (a.k.a request handler), which then receives the following parameters:

• req: An instance of http.IncomingMessage, plus some pre-built middlewares you can see here
• res: An instance of http.ServerResponse, plus some helper functions you can see here

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.

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:

API Middlewares

learn about the built-in middlewares for the request.

Response Helpers

learn about the built-in methods for the response.

TypeScript

Add TypeScript to your API Routes.