O que é API Routes?

As API Routes são Rotas de API criadas dentro de uma aplicação NextJS visando substituir a utilização de um backend.

Ok, isso parece forte. O mais comum é vermos aplicações Front-End e Back-End sendo criadas separadamente.

Mas, as API Routes do Next buscam entregar uma alternativa para esse padrão.

Como criar rotas com a API Routes?

Dentro da sua aplicação Next, na pasta /pages, crie a rota /pages/api, tudo que é criado ai dentro, funciona de forma semelhante as rotas de páginas.

Se quisermos criar a seguinte rota na aplicação: /api/example, basta criar um arquivo example.js em /pages/api.

Dessa forma:

- pages
  - api
    - example.js

Para que uma rota criada funcione corretamente, precisamos exportar uma função padrão, que receba os parâmetros req e res.

export default function handler(req, res) {
   
}

Trabalhando com diferentes métodos com Routes API (GET, POST, UPDATE, DELETE)

Para trabalhar com diferentes métodos utilizando Routes API, basta utilizarmos algum meio de verificação no objeto req.method.

export default function handler(req, res) {
  if (req.method === 'POST') {
    // Process a POST request
  } else {
    // Handle any other HTTP method
  }
}
// ou
export default function handler(req, res) {
  switch (req.method) {
    case 'POST':
      // Process a POST request
    // Handle any other HTTP method
    default:
      // Default process
  }
}

Criando sua primeira API com API Routes

Dentro da pasta /api, crie um arquivo chamado hello.js e adicione o seguinte código:

export default function handler(req, res) {
  res.status(200).json({ message: 'Hello World' })
}

Agora, abra o seu localhost, no formato: localhost:3000/api/hello. Deu certo?

A partir de agora, você pode consumir essa rota dentro do seu Front-End em React.

Rotas dinâmicas com API Routes

Um dos pontos legais na criação de páginas com NextJS é a possibilidade de criarmos rotas dinâmicas.

Isso também é possível com as API Routes. Ou seja, rotas de API dinâmicas, como:

fetch('/user/001')
fetch('/user/002')
fetch('/user/003')

Como fazemos isso? Da mesma forma como fazemos nas páginas.

Para esse exemplo, podemos montar uma estrutura como essa:

- pages
  - api
    - user
      -[uid].js

Dessa forma, ao fazer uma requisição na rota, podemos acessar o valor de uid. Assim:

export default function handler(req, res) {
  const { uid } = req.query
}

Como retornar uma resposta JSON com API Routes?

Existe uma lista de métodos que pode te ajudar a criar as melhores respostas para sua API.

Para retornar uma resposta JSON, você pode fazer da seguinte maneira:

export default function handler(req, res) {
  res.status(200).json({ message: 'Hello from Next.js!' })
}

Aqui, temos dois ajudantes sendo utilizados: res.status() para definir o código de status e res.json() para retornar uma resposta JSON.

Criando API Routes com Typescript

O Next, por padrão, fornece os tipos de req e res para utilização em sua aplicação, dessa forma:

import type { NextApiRequest, NextApiResponse } from 'next'

export default function handler(req: NextApiRequest, res: NextApiResponse) {
  res.status(200).json({ message: 'Hello World' })
}