Itinéraires d’API Next.js : ce que vous devez savoir

Dans cet article, nous verrons comment configurer des routes d’API à l’aide de Next.js, de l’objet de requête et des assistants de réponse.

Il est important de se rappeler que certains sites Web offrent aux visiteurs plus qu’un simple service de pages Web. Dans certaines situations, nous pouvons avoir besoin d’un backend pour gérer des fonctionnalités telles que permettre aux utilisateurs de s’inscrire à des newsletters, recevoir les commentaires des utilisateurs, récupérer des données à partir d’une base de données, etc.

Suivant.js introduit le Itinéraires d’API fonctionnalité de la version 9 pour nous permettre de créer des points de terminaison d’API dans le cadre de notre application Next.js sans avoir à écrire de code de serveur personnalisé supplémentaire.

Cet article passera en revue les composants cruciaux des routes de l’API Next.js. Nous verrons comment utiliser Next.js pour configurer les routes d’API, l’objet de requête, les helpers de réponse et d’autres concepts.

Présentation du fonctionnement des routes de l’API Next.js

Next.js exploite la structure de dossiers de l’application pour créer des itinéraires d’API. Dans le pages dossier au niveau racine de l’application, il y a un api dossier déjà ajouté par create-next-app. Vous pouvez créer des fichiers JavaScript dans ce dossier pour représenter toutes les routes d’API de votre application.

Next.js mappe n’importe quel fichier dans le pages/api dossier à /api/<file-name> et les traite comme une route API au lieu d’une page. Par exemple, la création d’un pages/api/products.js fichier va créer un /api/products Itinéraire API. Nous pouvons également créer le /api/products route en ajoutant un pages/api/products/index.js dossier. Il permet également le mécanisme de fichier d’index similaire à celui du routage côté client dans Next.js.

Avec cela, vous pouvez écrire du code backend et ajouter une logique métier à votre application sans avoir à configurer d’autres routes d’API ni à écrire de code de serveur personnalisé supplémentaire. Pour qu’une route d’API fonctionne, chaque fichier doit exporter une fonction par défaut qui accepte deux paramètres : les objets de requête et de réponse.

Configuration du projet

Créer un Suivant.js application à l’aide de la commande suivante :

npx create-next-app api-demo

Création d’une route d’API

Créez un nouveau fichier appelé first-route.js dans le pages/api dossier et ajoutez-y ce qui suit :

export default function handler(req, res) {
  res.status(200).json({ message: "My first API route" });
}

Ouais c’est ça! Créer une route d’API avec Next.js est aussi simple que cela.

Nous avons ajouté une fonction au fichier nouvellement créé. La fonction sert de contrôleur qui gère les requêtes arrivant sur cette route (pages/api/first-route). Il prend deux paramètres et renvoie une réponse avec un statut et un objet JSON à l’aide de certains assistants de réponse prédéfinis. Plus de détails sur l’objet de requête et les assistants de réponse seront donnés dans les sections suivantes de cet article.

Une autre logique dorsale peut être ajoutée aux fichiers de route, mais elle doit toujours respecter l’exigence d’exporter une fonction par défaut.

Pour tester si la route de l’API fonctionne, ouvrez votre navigateur et accédez à pages/api/first-route pour afficher la réponse de l’API.

L’objet de requête

Comme indiqué précédemment, la méthode de gestionnaire d’itinéraire de l’API Next.js reçoit deux arguments, dont l’un est l’objet de requête (req). Le req object est une instance de http.IncomingMessage et représente les informations de demande reçues du client qui envoie la demande. Il comprend également les en-têtes de requête, la méthode de requête, l’URL demandée, etc.

Next.js fournit également des middlewares intégrés pour l’analyse et l’extension de l’objet de requête entrante (req). Ce sont les middlewares :

• corps requis: Par défaut, Next.js analyse le corps de la requête, vous n’avez donc pas besoin d’installer un autre module d’analyseur de corps tiers. req.body comprend un objet analysé par content-type tel que spécifié par le client. Il est par défaut à null si aucun corps n’a été spécifié.

• req.query : Next.js analyse également la chaîne de requête attachée à l’URL de la requête. req.query est un objet contenant les paramètres de la requête et leurs valeurs, ou un objet vide {} si aucune chaîne de requête n’était jointe.

• cookies requis: Il contient les cookies envoyés par la requête. Il est également par défaut un objet vide {} si aucun cookie n’est spécifié.

Les aides à la réponse

L’autre moitié des deux paramètres requis définis dans les gestionnaires de route de l’API est l’objet de réponse (res). Il s’agit d’une instance de http.ServerResponse, avec des méthodes d’assistance supplémentaires qui permettent d’améliorer l’expérience du développeur et d’accélérer la création de nouveaux points de terminaison d’API.

Voici quelques-unes des méthodes d’assistance :

• res.json(corps): Il est utilisé pour renvoyer une réponse JSON au client. Il prend comme argument un objet qui doit être sérialisable.

export default function handler(req, res) {
  res.json({
    message: "Successful",
    data: { name: "A new JSON API reponse data" },
  });
}

• res.send(corps): Utilisé pour envoyer la réponse HTTP. Le corps peut être une chaîne, un objet ou un tampon.

export default function handler(req, res) {
  res.send("Hello world!!...");
}

• res.status(code): Il s’agit d’une fonction utilisée pour définir le code d’état de la réponse. Il accepte un code d’état HTTP valide comme argument.

export default function handler(req, res) {
  try {
    
    res.status(200).json({
      message: "Successful",
      data: { data },
    });
  } catch (error) {
    res.status(500).json({
      error,
    });
  }
}

Dans le code ci-dessus, nous avons défini une fonction de gestionnaire d’itinéraire qui renvoie un code d’état et un objet de réponse différents selon qu’une erreur se produit ou non.

Vous pouvez en savoir plus ici sur les autres méthodes d’aide à la réponse fournies par Next.js.

Gestion de plusieurs verbes HTTP

Lorsque vous travaillez avec des routes/points de terminaison d’API, il est courant d’utiliser des noms qui représentent l’entité du point de terminaison que nous récupérons ou manipulons comme nom de chemin au lieu d’utiliser des verbes dans nos chemins de point de terminaison.

Par exemple, au lieu d’avoir des itinéraires séparés pour obtenir des utilisateurs—/pages/api/getUsersmettre à jour les utilisateurs—pages/api/updateUsersajouter des utilisateurs—pages/api/addUsersnous voulons avoir une seule route pages/api/users mais avec une méthode de requête différente pour spécifier l’action que nous voulons. Dans notre cas, GET, PATCH et POST.

Les routes d’API Next.js nous permettent de spécifier plusieurs verbes HTTP pour la même route d’API dans un seul fichier. Pour travailler avec cela, vous devez utiliser une instruction conditionnelle pour différencier les différentes méthodes de requête avec lesquelles vous souhaitez travailler dans votre route API.

Un exemple utilisant l’instruction switch est illustré ci-dessous :

    export default function handler(req, res) {
        switch (req.method) {
          case 'GET':
            
            res.status(200).json({
            break;

          case 'POST':
            
            res.status(201).json({
            break;

          case 'PATCH':
            
            res.status(200).json({
            break;

          default:
            res.status(405).end(`${method} Not Allowed`);
            break;
        }
      }

Dans le code ci-dessus, nous avons défini une instruction switch qui nous permet d’exécuter des extraits de code et de renvoyer des réponses différentes pour chaque cas de la méthode de requête. Nous avons également spécifié une condition par défaut qui génère une erreur si aucun des cas n’est satisfait.

Il existe également une bibliothèque appelée next-connect connue sous le nom de routeur minimal et de couche middleware pour Next.js. Il utilise une approche similaire à Express.js pour le routage API. Cela simplifie également la gestion de divers verbes HTTP. Tu peux En savoir plus ici.

Routes d’API dynamiques

Next.js nous permet de créer des routes d’API dynamiques similaires à la convention utilisée pour le routage côté client dans Next.js. Pour créer une route API dynamique, placez le nom du fichier de route entre crochets, par exemple urn:uuid:8695f73b-a269-4b51-9451-d3865037fbfa.js.

Créons une route d’API dynamique. Créer un fichier nommé [userId].js dans le page/api dossier et ajoutez-y ce qui suit :

export default function handler(req, res) {
  const { userId } = req.query;
  
  res.status(200).json({ userId });
}

Tout comme le routage côté client, Next.js nous permet également de définir une route API fourre-tout, c’est-à-dire que nous pouvons avoir plusieurs segments de chemin dynamiques dans une route API. Pour ce faire, ajoutez trois points à l’intérieur des crochets avant le nom du fichier. par exemple […slug].js.

Création d’un fichier de route fourre-tout comme pages/api/products/[…slug].js correspondra /api/products/ball, /api/products/ball/red, /api/products/ball/red/big etc.

Les valeurs de paramètre correspondantes ne seront pas envoyées en tant qu’objet de requête, mais collectées dans un tableau à la place. Par conséquent, pour les trois routes que nous avons utilisées comme exemple, nous aurons les objets {"slug": ["ball"]}, {"slug": ["ball", "red"]} et
{"slug": ["ball", "red", "big"]}respectivement.

En outre, les routes d’API prédéfinies sont prioritaires sur les routes d’API dynamiques, et les routes d’API dynamiques sont prioritaires sur les routes d’API fourre-tout.

Définir des configurations personnalisées

Next.js fournit un objet de configuration qui, une fois exporté, peut être utilisé pour modifier certaines des configurations par défaut de l’application. Il a un imbriqué api objet qui traite des configurations disponibles pour les routes d’API.

Par exemple, nous pouvons désactiver l’analyseur de corps par défaut fourni par Next.js.

export default function handler(req, res) {
  
}
export const config = {
  api: {
    bodyParser: false,
  },
};

Nous pouvons définir de nombreuses autres configurations d’API personnalisées à l’aide de l’objet de configuration. Cliquez ici lien pour apprendre plus.

Utilisation de middlewares tiers

L’équipe Next.js fournit un runMiddleware fonction d’assistance qui vous permet d’exécuter n’importe quel middleware compatible Connect (une couche middleware pour Node.js).

function runMiddleware(req, res, fn) {
  return new Promise((resolve, reject) => {
    fn(req, res, (result) => {
      if (result instanceof Error) {
        return reject(result);
      }
      return resolve(result);
    });
  });
}

La fonction d’assistance prend l’objet de requête, l’objet de réponse et une instance du middleware tiers comme paramètres. Il attend que le middleware s’exécute avant de continuer et génère une erreur en cas d’échec.

Vous pouvez maintenant utiliser la fonction d’assistance pour exécuter n’importe quel middleware compatible Connect dans votre application. Par exemple, pour configurer CORS (Cross-Origin Resource Sharing) pour votre route API, ouvrez votre terminal et à la racine de votre application, exécutez la commande suivante pour installer le package cors en tant que dépendance :

npm install cors

Ensuite, ouvrez votre fichier de routage d’API et ajoutez-y les éléments suivants :

    import Cors from 'cors'
    const cors = Cors({
      methods: ['GET', 'HEAD', 'POST'],
    })
    function runMiddleware(req, res, fn) {
      return new Promise((resolve, reject) => {
        fn(req, res, (result) => {
          if (result instanceof Error) {
            return reject(result);
          }
          return resolve(result);
        });
      });
    }
    export default async function handler(req, res) {
      await runMiddleware(req, res, cors)
      
      res.status(
    }

Dans le code ci-dessus, nous avons importé Cors et en avons créé une instance. Nous avons ensuite exécuté le middleware en utilisant le runMiddleware fonction d’assistance à l’intérieur du handler une fonction.

Conclusion

Dans cet article, nous avons examiné la configuration d’une route d’API dans Next.js. Next.js simplifie le processus d’implémentation d’une API pour vos applications. Il offre quelques avantages : il ne nécessite aucune configuration, isole chaque gestionnaire en tant que fonction autonome, dispose d’un excellent support middleware, etc.