Le but de cet article est de vous montrer comment utiliser Node.js et le framework Express pour créer un point de terminaison d'API. Nous allons apprendre cela en construisant une application qui convertit la syntaxe Markdown en HTML. Nous allons également ajouter un mécanisme d'authentification à l'API afin d'éviter toute utilisation abusive de notre application.

Application Markode NodeJS

Notre toute petite application, que nous appellerons «Markdown Convertor», nous permettra de publier du texte de style Markdown et de récupérer une version HTML. L'application sera créée à l'aide du framework Node.js Express et supportera l'authentification pour les demandes de conversion.

Nous allons créer l'application par petites étapes: créer un échafaudage à l'aide d'Express, puis ajouter diverses fonctionnalités telles que l'authentification au fur et à mesure. Commençons donc par la phase initiale de création de l’application en créant un échafaudage.

Étape 1: Installation d’Express

Si vous avez déjà installé Node.js sur votre système, créez un répertoire pour y stocker votre application ( appelez-la “ markdown-api ”) et passez à ce répertoire:

 $ mkdir markdown-api
$ cd markdown-api

Utilisez la commande npm init pour créer un fichier package.json pour votre application. Cette commande vous invite à indiquer un certain nombre d'éléments, tels que le nom et la version de votre application.

Pour l'instant, il vous suffit d'appuyer sur . Entrez pour accepter les valeurs par défaut pour la plupart d'entre elles. J'ai utilisé le fichier de point d'entrée par défaut sous le nom index.js mais vous pouvez essayer app.js ou un autre selon vos préférences.

Installez maintenant Express dans markdown-api répertoire et enregistrez-le dans la liste des dépendances:

 $ npm install express --save

Créez un fichier index.js dans le répertoire actuel ( markdown-api ) et ajoutez le code suivant pour vérifier si l'infrastructure Express est correctement installée:

 Const express = nécessite ('express');
var app = express ();
 
app.get ('/', fonction (req, res) {
    res.send ('Hello World!');
});
 
app.listen (3000);

Recherchez maintenant l'URL http: // localhost: 3000 pour vérifier si le fichier de test fonctionne correctement. Si tout est en ordre, nous verrons apparaître un message d'accueil Hello World! 'Dans le navigateur et nous pourrons alors créer une API de base pour convertir Markdown en HTML.

Étape 2: Création d'une API de base

Notre API consistera à convertir le texte en syntaxe Markdown en HTML. L'API comportera deux points d'extrémité:

Le point d'extrémité login permettra à l'application d'authentifier les requêtes valides, tandis que le point d'extrémité convert convertira (évidemment) Markdown en HTML.

Au-dessous. est le code de l'API de base pour appeler les deux points de terminaison. L'appel login renvoie simplement une chaîne «Authenticated», tandis que l'appel convert renvoie le contenu Markdown que vous avez soumis à l'application. La méthode home renvoie simplement une chaîne ‘Hello World!’.

 const express = require ("express");
const bodyParser = require ('analyseur de corps');
    
var app = express ();
app.use (bodyParser.urlencoded ({extended: true}));
app.use (bodyParser.json ());
 
app.get ('/', fonction (req, res) {
    res.send ('Hello World!');
});
 
app.post ('/ login', fonction (req, res) {
    res.send ("authentifié");
  },
)
 
app.post ("/ convert", fonction (req, res, next) {
    console.log (req.body);
    if (typeof req.body.content == 'undefined' || req.body.content == null) {
        rés.json (["error", "No data found"]);
    } autre {
        rés.json (["markdown", req.body.content]);
    }
});
 
app.listen (3000, function () {
 console.log ("serveur fonctionnant sur le port 3000");
});

Nous utilisons le middleware de l'analyseur de corps pour faciliter l'analyse des demandes entrantes dans les applications. Le middleware mettra toutes les requêtes entrantes à votre disposition sous la propriété req.body . Vous pouvez vous passer du middleware supplémentaire, mais son ajout facilite grandement l'analyse de divers paramètres de requête entrante.

Vous pouvez installer l'analyseur de corps simplement en utilisant npm:

 $ npm install body-parser.

Maintenant que nos fonctions de module factice sont en place, nous allons utiliser Postman pour le tester. Commençons d'abord par un bref aperçu de Postman.

Présentation de Postman

Postman est un outil de développement d'API qui facilite la création, la modification et le test de points de terminaison d'API à partir d'un navigateur ou en téléchargeant une application de bureau. maintenant obsolète). Il a la capacité de faire différents types de requêtes HTTP, à savoir GET, POST, PUT, PATCH. Il est disponible pour Windows, macOS et Linux.

Voici un avant-goût de l'interface de Postman:

Pour interroger un point de terminaison de l'API, vous ' Vous devez suivre les étapes suivantes:

1. Entrez l'URL que vous souhaitez interroger dans la barre d'URL de la section supérieure;
2. Sélectionnez la méthode HTTP située à gauche de la barre d'URL pour envoyer la demande;
3. Cliquez sur le bouton 'Envoyer'.

Postman envoie ensuite la demande à l'application, récupère les réponses et les affiche dans la fenêtre du bas. Ceci est le mécanisme de base sur la façon d'utiliser l'outil Postman. Dans notre application, nous devrons également ajouter d'autres paramètres à la demande, qui seront décrits dans les sections suivantes:

Utilisation de Postman

Maintenant que nous avons vu un aperçu de Postman, passons maintenant à son utilisation pour notre application.

Lancez votre application markdown-api à partir de la ligne de commande:

 $ node index.js 

Pour tester le code de l'API de base, nous effectuons des appels API à l'application à partir de Facteur. Notez que nous utilisons la méthode POST pour transmettre le texte à convertir dans l'application.

L'application accepte actuellement le contenu Markdown à convertir via le paramètre content content. Ceci nous passons comme un format encodé en URL. Actuellement, l’application renvoie la chaîne textuelle au format JSON – le premier champ renvoyant toujours la chaîne markdown et le second champ renvoyant le texte converti. Plus tard, lorsque nous ajouterons le code de traitement Markdown, le texte converti sera renvoyé.

Étape 3: Ajout du convertisseur de Markdown

L’échafaudage d’application étant désormais construit, nous pouvons examiner la bibliothèque JavaScript Showdown . que nous allons utiliser pour convertir Markdown en HTML. Showdown est un convertisseur bidirectionnel Markdown vers HTML écrit en Javascript qui vous permet de convertir Markdown en HTML et vice-versa.

Installez le paquet en utilisant npm:

 $ npm install showdown

Après avoir ajouté le code de confrontation requis à l'échafaud, nous obtenons le résultat suivant:

 const express = require ("express");
const bodyParser = require ('analyseur de corps');
const showdown = require ('showdown');
    
var app = express ();
app.use (bodyParser.urlencoded ({extended: true}));
app.use (bodyParser.json ());
 
convertisseur = nouveau showdown.Converter ();

app.get ('/', fonction (req, res) {
    res.send ('Hello World!');
});
 
app.post ('/ login', fonction (req, res) {
    res.send ("authentifié");
  },
)
 
app.post ("/ convert", fonction (req, res, next) {
    if (typeof req.body.content == 'undefined' || req.body.content == null) {
        rés.json (["error", "No data found"]);
    } autre {
        text = req.body.content;
        html = converter.makeHtml (text);
        rés.json (["markdown", html]);
    }
});
 
app.listen (3000, function () {
 console.log ("serveur fonctionnant sur le port 3000");
});

Le code du convertisseur principal se trouve dans le point de terminaison / convert extrait et présenté ci-dessous. Cela convertira le texte Markdown que vous publiez en une version HTML et le renverra sous forme de document JSON.

 ...
} autre {
        text = req.body.content;
        html = converter.makeHtml (text);
        rés.json (["markdown", html]);
    }

La méthode utilisée pour la conversion est converter.makeHtml (text) . Nous pouvons définir diverses options pour la conversion de Markdown à l'aide de la méthode setOption au format suivant:

 converter.setOption ('optionKey', 'value');

Ainsi, par exemple, nous pouvons définir une option pour insérer et lier automatiquement une URL spécifiée sans annotation.

 converter.setOption ('restrictedAutoLink', 'true');

Comme dans l'exemple de Postman, si nous transmettons une chaîne simple (telle que Google home http://www.google.com/) à l'application, la chaîne suivante sera renvoyée si simplifié AutoLink est activé:

 maison Google  http://www.google.com/  

Sans l'option, nous devrons ajouter des informations de balisage pour obtenir les mêmes résultats:

 Google home 

Il existe de nombreuses options pour modifier le traitement de Markdown. Une liste complète est disponible sur le site Web Passport.js .

Nous avons maintenant un convertisseur Markdown-to-HTML fonctionnel avec un seul point de terminaison. Allons plus loin et ajoutons l'authentification pour avoir une application.

Étape 4: Ajout de l'authentification d'API à l'aide de Passport

Exposer votre API d'application au monde extérieur sans authentification appropriée encouragera les utilisateurs à interroger le point de terminaison de son API sans restrictions. Cela invitera des éléments peu scrupuleux à utiliser votre API de manière abusive et surchargera votre serveur de requêtes non modérées. Pour atténuer cela, nous devons ajouter un mécanisme d'authentification approprié.

Nous allons utiliser le package Passport pour ajouter une authentification à notre application. Tout comme le middleware body-parser rencontré précédemment, Passport est un middleware d'authentification pour Node.js. La raison pour laquelle nous utiliserons Passport est qu’il dispose de nombreux mécanismes d’authentification (nom d’utilisateur et mot de passe, Facebook, Twitter, etc.), ce qui donne à l’utilisateur la possibilité de choisir un mécanisme particulier. Un middleware Passport peut être facilement inséré dans n'importe quelle application Express sans changer beaucoup de code.

Installez le package à l'aide de npm.

 $ npm install passport

Nous allons également utiliser la stratégie locale qui sera expliquée plus tard, pour l'authentification. Alors installez-le aussi.

 $ npm installer passport-local

Vous devrez également ajouter le module d'encodage et de décodage JWT (JSON Web Token) pour Node.js utilisé par Passport:

 $ npm install jwt-simple.

Strategies In Passport

Passport utilise le concept de stratégies pour authentifier les demandes. Les stratégies sont diverses méthodes qui vous permettent d'authentifier les demandes. Elles peuvent aller du simple cas à la vérification des informations d'identification du nom d'utilisateur et du mot de passe, de l'authentification à l'aide de OAuth (Facebook ou Twitter) ou de OpenID. Avant d'authentifier les demandes, la stratégie utilisée par une application doit être configurée.

Dans notre application, nous utiliserons un schéma simple d'authentification par nom d'utilisateur et mot de passe, car il est simple à comprendre et à coder. Actuellement, Passport prend en charge plus de 300 stratégies qui peuvent être trouvées ici.

Bien que la conception de Passport puisse paraître compliquée, son implémentation dans le code est très simple. Voici un exemple qui montre comment notre point de terminaison / convert est décoré pour l'authentification. Comme vous le verrez, ajouter l’authentification à une méthode est assez simple.

 app.post ("/ convert",
         passport.authenticate ('local', {session: false, failWithError: true}),
         fonction (req, res, next) {
        // Si cette fonction est appelée, l'authentification a réussi.
        // Vérifie également si aucun contenu n'est envoyé
        if (typeof req.body.content == 'undefined' || req.body.content == null) {
            rés.json (["error", "No data found"]);
        } autre {
            text = req.body.content;
            html = converter.makeHtml (text);
            rés.json (["markdown", html]);
        }},
        // Retourne un message 'Unauthorized' si l'authentification a échoué.
        fonction (err, req, res, next) {
            return res.status (401) .send ({succès: false, message: err})
        });

Maintenant, avec la chaîne Markdown à convertir, nous devons également envoyer un nom d'utilisateur et un mot de passe. Ceci sera vérifié avec notre nom d'utilisateur et mot de passe de l'application et vérifié. Comme nous utilisons une stratégie locale pour l'authentification, les informations d'identification sont stockées dans le code lui-même.

Bien que cela puisse sembler un cauchemar pour la sécurité, il est suffisant pour les applications de démonstration. Cela facilite également la compréhension du processus d'authentification dans notre exemple. Incidemment, une méthode de sécurité commune utilisée consiste à stocker les informations d'identification dans des variables d'environnement. Néanmoins, beaucoup de gens ne sont peut-être pas d'accord avec cette méthode, mais je trouve cela relativement sûr.

L'exemple complet avec authentification est présenté ci-dessous.

 const express = require ("express");
const showdown = require ('showdown');
const bodyParser = require ('analyseur de corps');
const passport = require («passeport»);
const jwt = require ('jwt-simple');
const LocalStrategy = require ('passport-local'). Stratégie;
 
    
var app = express ();
app.use (bodyParser.urlencoded ({extended: true}));
app.use (bodyParser.json ());
 
convertisseur = nouveau showdown.Converter ();
 
const ADMIN = 'admin';
const ADMIN_PASSWORD = 'smagazine';
const SECRET = 'secret # 4456';
 
passport.use (new LocalStrategy (fonction (nom d'utilisateur, mot de passe, done)) {
  if (nom d'utilisateur === ADMIN && mot de passe === ADMIN_PASSWORD) {
    done (null, jwt.encode ({nom d'utilisateur}, SECRET));
    revenir;
  }
  done (null, false);
}));
 
app.get ('/', fonction (req, res) {
    res.send ('Hello World!');
});
 
 
app.post ('/ login', passport.authenticate ('local', {session: false}),
                fonction (req, res) {
                // Si cette fonction est appelée, l'authentification a réussi.
                // retourne une chaîne 'authentifiée'.
                res.send ("authentifié");
  });
  
 
app.post ("/ convert",
         passport.authenticate ('local', {session: false, failWithError: true}),
         fonction (req, res, next) {
        // Si cette fonction est appelée, l'authentification a réussi.
        // Vérifie également si aucun contenu n'est envoyé
        if (typeof req.body.content == 'undefined' || req.body.content == null) {
            rés.json (["error", "No data found"]);
        } autre {
            text = req.body.content;
            html = converter.makeHtml (text);
            rés.json (["markdown", html]);
        }},
        // Retourne un message 'Unauthorized' si l'authentification a échoué.
        fonction (err, req, res, next) {
            return res.status (401) .send ({succès: false, message: err})
        });
 
 
app.listen (3000, function () {
 console.log ("serveur fonctionnant sur le port 3000");
});

Une session Postman présentant la conversion avec authentification ajoutée est présentée ci-dessous.

Ici, nous pouvons voir que nous avons obtenu une chaîne HTML convertie appropriée à partir d'une syntaxe Markdown. Bien que nous n'ayons demandé de convertir qu'une seule ligne de Markdown, l'API peut convertir une plus grande quantité de texte.

Ceci conclut notre incursion brève dans la création d'un point de terminaison d'API à l'aide de Node.js et Express. La construction d'API est un sujet complexe et vous devez connaître certaines nuances plus fines lorsque vous en construisez une, ce que nous n'avons malheureusement pas le temps de laisser ici mais que nous aborderons peut-être dans de futurs articles.

Accès à notre API à partir d'une autre application

Maintenant Si nous avons construit une API, nous pouvons créer un petit script Node.js qui vous montrera comment accéder à l’API. Pour notre exemple, nous devrons installer le paquet npm request qui fournit un moyen simple de faire des requêtes HTTP. (Vous aurez probablement déjà déjà installé ceci.)

 $ npm install request --save

L'exemple de code permettant d'envoyer une demande à notre API et d'obtenir la réponse est donné ci-dessous. Comme vous pouvez le constater, le paquet de demande simplifie considérablement le sujet. La démarque à convertir se trouve dans la variable textToConvert .

Avant d'exécuter le script suivant, assurez-vous que l'application API créée précédemment est déjà en cours d'exécution. Exécutez le script suivant dans une autre fenêtre de commande:

Remarque : Nous utilisons le signe (Back-tick) pour couvrir plusieurs lignes JavaScript pour le texte . variable. Ce n'est pas une simple citation.

 var Request = require ("request");
 
// Début du démarquage
var textToConvert = `Heading
=======
## Sous-rubrique
 
Les paragraphes sont séparés
par une ligne blanche.
 
Deux espaces au bout d'une ligne
produit un saut de ligne.
 
Attributs de texte _italic_,
** gras **, 'monospace'.
A https://www.smashingmagazine.com/2019/04/nodejs-express-api-markdown-html/ (http://example.com).
Règle horizontale: `;
 
// Fin du démarquage
                    
Request.post ({
    "en-têtes": {"content-type": "application / json"},
    "url": "http: // localhost: 3000 / convert",
    "body": JSON.stringify ({
        "contenu": textToConvert,
        "nom d'utilisateur": "admin",
        "mot de passe": "smagazine"
    })
}, fonction (erreur, réponse, corps) {
    // Si nous avons une erreur de connexion, renflouer.
    si (erreur) {
        retourne console.log (erreur);
    }
    // sinon afficher le texte converti
    console.dir (JSON.parse (body));
});

Lorsque nous adressons une demande POST à ​​notre API, nous fournissons le texte Markdown à convertir avec les informations d'identification. Si nous fournissons des informations d'identification erronées, nous recevrons un message d'erreur.

 {
  succès: faux
  message: {
    nom: 'AuthenticationError',
    message: 'Non autorisé',
    statut: 401
  }
}

Pour une demande correctement autorisée, l'échantillon ci-dessus Markdown sera converti comme suit:

 ['markdown',
  `
 Heading 
  
 Sous-titre 
  
 Les paragraphes sont séparés par une ligne vierge. 
  
 Deux espaces au bout d'une ligne 

  produit un retour à la ligne. 
  
 Attributs du texte  italique ,
   gras "monospace".
  Un lien  .
  Règle horizontale: 
 `]

Bien que nous ayons codé en dur le Markdown ici, le texte peut provenir d'autres sources – fichiers, formulaires Web, etc. Le processus de demande reste le même.

Notez que, comme nous envoyons la demande en tant que type de contenu application / json ; nous devons encoder le corps en utilisant json, d'où l'appel de fonction JSON.stringify . Comme vous pouvez le constater, il suffit d'un très petit exemple pour tester une application API.

Conclusion

Dans cet article, nous avons lancé un didacticiel visant à apprendre à utiliser Node, js et le framework Express. construire un point de terminaison API. Plutôt que de créer une application fictive sans but, nous avons décidé de créer une API qui convertit la syntaxe Markdown en HTML, qui ancre ou permet l'apprentissage dans un contexte utile. En cours de route, nous avons ajouté une authentification à notre point de terminaison API et nous avons également trouvé des moyens de tester notre point de terminaison d'application à l'aide de Postman.

(rb, ra, il)