Construirea unui API Node.js Express pentru a converti Markdown în HTML

Markdown este un limbaj ușor de marcare a textului, care permite ca textul marcat să fie convertit în diferite formate. Scopul inițial al creării Markdown a fost de a le permite oamenilor „să scrie folosind un format de text simplu ușor de citit și ușor de scris” și, opțional, să îl convertească în XHTML (sau HTML) valid structural. În prezent, cu WordPress acceptă Markdown, formatul a devenit și mai utilizat pe scară largă.

Scopul scrierii articolului este de a vă arăta cum să utilizați Node.js și cadrul Express pentru a crea un punct final API. Contextul în care vom învăța acest lucru este prin construirea unei aplicații care convertește sintaxa Markdown în HTML. De asemenea, vom adăuga un mecanism de autentificare la API pentru a preveni utilizarea greșită a aplicației noastre.

O aplicație Markdown Node.js

Aplicația noastră micuță, pe care o vom numi „Markdown Converter”, ne va permite să postăm text în stil Markdown și să recuperăm o versiune HTML. Aplicația va fi creată folosind cadrul Node.js Express și va suporta autentificarea pentru cererile de conversie.

Vom construi aplicația în etape mici - inițial creând o schelă folosind Express și apoi adăugând diverse caracteristici, cum ar fi autentificarea pe măsură ce mergem. Deci, să începem cu etapa inițială a construirii aplicației prin crearea unei schele.

Etapa 1: Instalarea Express

Presupunând că ați instalat deja Node.js pe sistemul dvs., creați un director pentru a vă păstra aplicația (să o numim „ markdown-api ”) și comutați la acel director:

 $ mkdir markdown-api $ cd markdown-api

Utilizați comanda npm init pentru a crea un fișier package.json pentru aplicația dvs. Această comandă vă solicită o serie de lucruri, cum ar fi numele și versiunea aplicației dvs.

Pentru moment, apăsați pur și simplu Enter pentru a accepta valorile implicite pentru majoritatea dintre ele. Am folosit fișierul de punct de intrare implicit ca index.js , dar puteți încerca app.js sau altul, în funcție de preferințele dvs.

Acum instalați Express în directorul markdown-api și salvați-l în lista de dependențe:

 $ npm install express --save

Creați un fișier index.js în directorul curent ( markdown-api ) și adăugați următorul cod pentru a testa dacă cadrul Express este instalat corect:

 Const express = require('express'); var app = express(); app.get('/', function(req, res){ res.send('Hello World!'); }); app.listen(3000);

Acum navigați la adresa URL https://localhost:3000 pentru a verifica dacă fișierul de testare funcționează corect. Dacă totul este în ordine, vom vedea un Hello World!' salut în browser și putem continua la construirea unui API de bază pentru a converti Markdown în HTML.

Etapa 2: Construirea unui API de bază

Scopul principal al API-ului nostru va fi convertirea textului într-o sintaxă Markdown în HTML. API-ul va avea două puncte finale:

• /login
• /convert

Punctul final de login va permite aplicației să autentifice cereri valide, în timp ce punctul final de convert va converti (evident) Markdown în HTML.

Mai jos este codul API de bază pentru apelarea celor două puncte finale. Apelul de login returnează doar un șir „Autentificat”, în timp ce apelul de convert returnează orice conținut Markdown pe care l-ați trimis în aplicație. Metoda acasă doar returnează un „Hello World!” şir.

 const express = require("express"); const bodyParser = require('body-parser'); var app = express(); app.use(bodyParser.urlencoded({ extended: true })); app.use(bodyParser.json()); app.get('/', function(req, res){ res.send('Hello World!'); }); app.post('/login', function(req, res) { res.send("Authenticated"); }, ); app.post("/convert", function(req, res, next) { console.log(req.body); if(typeof req.body.content == 'undefined' || req.body.content == null) { res.json(["error", "No data found"]); } else { res.json(["markdown", req.body.content]); } }); app.listen(3000, function() { console.log("Server running on port 3000"); });

Folosim middleware-ul body-parser pentru a ușura analizarea cererilor primite către aplicații. Middleware-ul va pune la dispoziție toate solicitările primite în proprietatea req.body . Puteți face fără middleware-ul suplimentar, dar adăugarea acestuia face mult mai ușoară analizarea diferiților parametri de solicitare primită.

Puteți instala body-parser folosind pur și simplu npm:

 $ npm install body-parser

Acum că avem funcțiile stub inactiv, vom folosi Postman pentru a testa același lucru. Să începem mai întâi cu o scurtă prezentare a Poștașului.

Prezentare generală a poștașului

Postman este un instrument de dezvoltare API care facilitează construirea, modificarea și testarea punctelor finale API dintr-un browser sau prin descărcarea unei aplicații desktop (versiunea de browser este acum depreciată). Are capacitatea de a face diverse tipuri de solicitări HTTP, adică GET, POST, PUT, PATCH. Este disponibil pentru Windows, macOS și Linux.

Iată o degustare a interfeței Postman:

Pentru a interoga un punct final API, va trebui să parcurgeți următorii pași:

1. Introduceți adresa URL pe care doriți să o interogați în bara de adrese URL din secțiunea de sus;
2. Selectați metoda HTTP din stânga barei URL pentru a trimite cererea;
3. Faceți clic pe butonul „Trimite”.

Poștașul va trimite apoi cererea către aplicație, va prelua orice răspuns și o va afișa în fereastra de jos. Acesta este mecanismul de bază pentru utilizarea instrumentului Postman. În aplicația noastră, va trebui să adăugăm și alți parametri la cerere, care vor fi descriși în secțiunile următoare.

Folosind Postman

Acum că am văzut o prezentare generală a Postman, să mergem mai departe în utilizarea acesteia pentru aplicația noastră.

Porniți aplicația markdown-api din linia de comandă:

 $ node index.js

Pentru a testa codul API de bază, facem apeluri API către aplicație de la Postman. Rețineți că folosim metoda POST pentru a transmite textul de convertit în aplicație.

În prezent, aplicația acceptă conținutul Markdown de convertit prin intermediul parametrului POST al content . Acesta îl transmitem ca un format codificat URL. Aplicația, în prezent, returnează șirul textual într-un format JSON - primul câmp returnând întotdeauna markdown șirului, iar al doilea câmp returnând textul convertit. Mai târziu, când adăugăm codul de procesare Markdown, acesta va returna textul convertit.

Etapa 3: Adăugarea Markdown Converter

Cu schela aplicației acum construită, ne putem uita în biblioteca JavaScript Showdown pe care o vom folosi pentru a converti Markdown în HTML. Showdown este un convertor bidirecțional Markdown în HTML scris în JavaScript, care vă permite să convertiți Markdown în HTML și înapoi.

Instalați pachetul folosind npm:

 $ npm install showdown

După adăugarea codului de confruntare necesar la schelă, obținem următorul rezultat:

 const express = require("express"); const bodyParser = require('body-parser'); const showdown = require('showdown'); var app = express(); app.use(bodyParser.urlencoded({ extended: true })); app.use(bodyParser.json()); converter = new showdown.Converter(); app.get('/', function(req, res){ res.send('Hello World!'); }); app.post('/login', function(req, res) { res.send("Authenticated"); }, ); app.post("/convert", function(req, res, next) { if(typeof req.body.content == 'undefined' || req.body.content == null) { res.json(["error", "No data found"]); } else { text = req.body.content; html = converter.makeHtml(text); res.json(["markdown", html]); } }); app.listen(3000, function() { console.log("Server running on port 3000"); });

Codul convertorului principal se află în punctul final /convert așa cum este extras și prezentat mai jos. Acest lucru va converti orice text Markdown pe care îl postați într-o versiune HTML și îl va returna ca document JSON.

 ... } else { text = req.body.content; html = converter.makeHtml(text); res.json(["markdown", html]); }

Metoda care face conversia este converter.makeHtml(text) . Putem seta diverse opțiuni pentru conversia Markdown folosind metoda setOption cu următorul format:

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

Deci, de exemplu, putem seta o opțiune pentru a insera și lega automat o adresă URL specificată fără nicio markup.

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

Ca și în exemplul Postman, dacă trecem un șir simplu (cum ar fi Google home https://www.google.com/ ) către aplicație, acesta va returna următorul șir dacă simplifiedAutoLink este activat:

 <p>Google home <a href="https://www.google.com/">https://www.google.com/</a></p>

Fără opțiune, va trebui să adăugăm informații de marcare pentru a obține aceleași rezultate:

 Google home <https://www.google.com/>

Există multe opțiuni pentru a modifica modul în care este procesată Markdown. O listă completă poate fi găsită pe site-ul Showdown.

Deci acum avem un convertor Markdown-to-HTML care funcționează cu un singur punct final. Să mergem mai departe și să adăugăm autentificare pentru a avea aplicație.

Etapa 4: Adăugarea autentificării API folosind Passport

Expunerea API-ului aplicației dvs. în lumea exterioară fără o autentificare adecvată va încuraja utilizatorii să interogheze punctul dvs. final API fără restricții. Acest lucru va invita elementele fără scrupule să utilizeze greșit API-ul și, de asemenea, vă va împovăra serverul cu solicitări nemoderate. Pentru a atenua acest lucru, trebuie să adăugăm un mecanism de autentificare adecvat.

Vom folosi pachetul Passport pentru a adăuga autentificare aplicației noastre. La fel ca middleware-ul body-parser pe care l-am întâlnit mai devreme, Passport este un middleware de autentificare pentru Node.js. Motivul pentru care vom folosi Passport este că are o varietate de mecanisme de autentificare cu care să lucrăm (nume de utilizator și parolă, Facebook, Twitter și așa mai departe), ceea ce oferă utilizatorului flexibilitatea în alegerea unui anumit mecanism. Un middleware Passport poate fi introdus cu ușurință în orice aplicație Express fără a schimba prea mult cod.

Instalați pachetul folosind npm.

 $ npm install passport

Vom folosi și strategia local , care va fi explicată mai târziu, pentru autentificare. Așa că instalează-l și tu.

 $ npm install passport-local

De asemenea, va trebui să adăugați modulul de codificare și decodare JWT (JSON Web Token) pentru Node.js, care este utilizat de Passport:

 $ npm install jwt-simple

Strategii în pașaport

Passport folosește conceptul de strategii pentru autentificarea cererilor. Strategiile sunt diverse metode care vă permit să autentificați cererile și pot varia de la un caz simplu, cum ar fi verificarea numelui de utilizator și a acreditărilor parolei, autentificarea folosind OAuth (Facebook sau Twitter) sau utilizarea OpenID. Înainte de autentificarea cererilor, trebuie configurată strategia utilizată de o aplicație.

În aplicația noastră, vom folosi o schemă simplă de autentificare cu nume de utilizator și parolă, deoarece este ușor de înțeles și de codat. În prezent, Passport acceptă peste 300 de strategii care pot fi găsite aici.

Deși designul lui Passport poate părea complicat, implementarea în cod este foarte simplă. Iată un exemplu care arată modul în care punctul nostru final /convert este decorat pentru autentificare. După cum veți vedea, adăugarea de autentificare la o metodă este destul de simplă.

 app.post("/convert", passport.authenticate('local',{ session: false, failWithError: true }), function(req, res, next) { // If this function gets called, authentication was successful. // Also check if no content is sent if(typeof req.body.content == 'undefined' || req.body.content == null) { res.json(["error", "No data found"]); } else { text = req.body.content; html = converter.makeHtml(text); res.json(["markdown", html]); }}, // Return a 'Unauthorized' message back if authentication failed. function(err, req, res, next) { return res.status(401).send({ success: false, message: err }) });

Acum, împreună cu șirul Markdown care urmează să fie convertit, trebuie să trimitem și un nume de utilizator și o parolă. Acest lucru va fi verificat cu numele de utilizator și parola aplicației noastre și verificat. Deoarece folosim o strategie locală pentru autentificare, acreditările sunt stocate în codul însuși.

Deși acest lucru poate suna ca un coșmar de securitate, pentru aplicațiile demo este suficient de bun. Acest lucru facilitează, de asemenea, înțelegerea procesului de autentificare din exemplul nostru. De altfel, o metodă de securitate comună utilizată este stocarea acreditărilor în variabilele de mediu. Totuși, mulți oameni s-ar putea să nu fie de acord cu această metodă, dar mi se pare relativ sigură.

Exemplul complet cu autentificare este prezentat mai jos.

 const express = require("express"); const showdown = require('showdown'); const bodyParser = require('body-parser'); const passport = require('passport'); const jwt = require('jwt-simple'); const LocalStrategy = require('passport-local').Strategy; var app = express(); app.use(bodyParser.urlencoded({ extended: true })); app.use(bodyParser.json()); converter = new showdown.Converter(); const ADMIN = 'admin'; const ADMIN_PASSWORD = 'smagazine'; const SECRET = 'secret#4456'; passport.use(new LocalStrategy(function(username, password, done) { if (username === ADMIN && password === ADMIN_PASSWORD) { done(null, jwt.encode({ username }, SECRET)); return; } done(null, false); })); app.get('/', function(req, res){ res.send('Hello World!'); }); app.post('/login', passport.authenticate('local',{ session: false }), function(req, res) { // If this function gets called, authentication was successful. // Send a 'Authenticated' string back. res.send("Authenticated"); }); app.post("/convert", passport.authenticate('local',{ session: false, failWithError: true }), function(req, res, next) { // If this function gets called, authentication was successful. // Also check if no content is sent if(typeof req.body.content == 'undefined' || req.body.content == null) { res.json(["error", "No data found"]); } else { text = req.body.content; html = converter.makeHtml(text); res.json(["markdown", html]); }}, // Return a 'Unauthorized' message back if authentication failed. function(err, req, res, next) { return res.status(401).send({ success: false, message: err }) }); app.listen(3000, function() { console.log("Server running on port 3000"); });

O sesiune Postman care arată conversia cu autentificare adăugată este afișată mai jos.

Aici putem vedea că avem un șir HTML corect convertit dintr-o sintaxă Markdown. Deși am solicitat doar convertirea unei singure linii de Markdown, API-ul poate converti o cantitate mai mare de text.

Aceasta încheie scurta noastră incursiune în construirea unui punct final API folosind Node.js și Express. Crearea API este un subiect complex și există nuanțe mai fine de care ar trebui să fii conștient în timp ce construiești unul, pe care, din păcate, nu avem timp pentru aici, dar poate că le vom acoperi în articolele viitoare.

Accesarea API-ului nostru dintr-o altă aplicație

Acum că am construit un API, putem crea un mic script Node.js care vă va arăta cum poate fi accesat API-ul. Pentru exemplul nostru, va trebui să instalăm pachetul request npm care oferă o modalitate simplă de a face cereri HTTP. (Cel mai probabil îl veți avea deja instalat.)

 $ npm install request --save

Exemplul de cod pentru a trimite o solicitare către API-ul nostru și pentru a obține răspunsul este prezentat mai jos. După cum puteți vedea, pachetul de request simplifică considerabil problema. Reducerea de convertit se află în variabila textToConvert .

Înainte de a rula următorul script, asigurați-vă că aplicația API pe care am creat-o mai devreme rulează deja. Rulați următorul script într-o altă fereastră de comandă.

Notă : folosim semnul (back-tick) pentru a acoperi mai multe linii JavaScript pentru variabila textToConvert . Acesta nu este un singur ghilime.

 var Request = require("request"); // Start of markdown var textToConvert = `Heading ======= ## Sub-heading Paragraphs are separated by a blank line. Two spaces at the end of a line produces a line break. Text attributes _italic_, **bold**, 'monospace'. A [link](https://example.com). Horizontal rule:`; // End of markdown Request.post({ "headers": { "content-type": "application/json" }, "url": "https://localhost:3000/convert", "body": JSON.stringify({ "content": textToConvert, "username": "admin", "password": "smagazine" }) }, function(error, response, body){ // If we got any connection error, bail out. if(error) { return console.log(error); } // Else display the converted text console.dir(JSON.parse(body)); });

Când facem o solicitare POST către API-ul nostru, oferim textul Markdown care urmează să fie convertit împreună cu acreditările. Dacă furnizăm acreditările greșite, vom fi întâmpinați cu un mesaj de eroare.

 { success: false, message: { name: 'AuthenticationError', message: 'Unauthorized', status: 401 } }

Pentru o solicitare autorizată corect, exemplul de Markdown de mai sus va fi convertit în următoarele:

 [ 'markdown', `<h1>Heading</h1> <h2>Sub-heading</h2> <p>Paragraphs are separated by a blank line.</p> <p>Two spaces at the end of a line<br /> produces a line break.</p> <p>Text attributes <em>italic</em>, <strong>bold</strong>, 'monospace'. A <a href="https://example.com">link</a>. Horizontal rule:</p>` ]

Deși am codificat aici Markdown, textul poate proveni din diverse alte surse - fișiere, formulare web și așa mai departe. Procesul de solicitare rămâne același.

Rețineți că, deoarece trimitem cererea ca tip de conținut application/json ; trebuie să codificăm corpul folosind json, de unde apelul funcției JSON.stringify . După cum puteți vedea, este nevoie de un exemplu foarte mic pentru a testa sau a aplica aplicația API.

Concluzie

În acest articol, ne-am angajat într-un tutorial cu scopul de a învăța cum să folosiți Node,js și cadrul Express pentru a construi un punct final API. În loc să construim o aplicație inactivă fără scop, am decis să creăm un API care convertește sintaxa Markdown în HTML, care ancorează sau învață într-un context util. Pe parcurs, am adăugat autentificarea la punctul nostru final API și am văzut, de asemenea, modalități de a testa punctul final al aplicației folosind Postman.