Markdown'ı HTML'ye Dönüştürmek İçin Bir Node.js Express API Oluşturma

Markdown, işaretlenen metnin çeşitli biçimlere dönüştürülmesine izin veren hafif bir metin biçimlendirme dilidir. Markdown oluşturmanın asıl amacı, insanların "okunması ve yazılması kolay bir düz metin biçimi kullanarak yazmalarını" ve isteğe bağlı olarak bunu yapısal olarak geçerli XHTML'ye (veya HTML'ye) dönüştürmelerini sağlamaktı. Şu anda, WordPress'in Markdown'ı desteklemesiyle, biçim daha da yaygın bir şekilde kullanılmaya başlandı.

Makaleyi yazmanın amacı, bir API uç noktası oluşturmak için Node.js ve Express çerçevesini nasıl kullanacağınızı size göstermektir. Bunu öğreneceğimiz bağlam, Markdown sözdizimini HTML'ye dönüştüren bir uygulama oluşturmaktır. Uygulamamızın kötüye kullanımını önlemek için API'ye bir kimlik doğrulama mekanizması da ekleyeceğiz.

Bir Markdown Node.js Uygulaması

'Markdown Converter' adını vereceğimiz ufacık uygulamamız, Markdown tarzı metin göndermemizi ve bir HTML sürümünü almamızı sağlayacak. Uygulama, Node.js Express çerçevesi kullanılarak oluşturulacak ve dönüştürme istekleri için kimlik doğrulamasını destekleyecektir.

Uygulamayı küçük aşamalarda oluşturacağız - başlangıçta Express kullanarak bir iskele oluşturacak ve daha sonra ilerledikçe kimlik doğrulama gibi çeşitli özellikler ekleyeceğiz. Öyleyse, bir iskele oluşturarak uygulamayı oluşturmanın ilk aşamasıyla başlayalım.

Aşama 1: Express'i Yükleme

Node.js'yi sisteminize zaten yüklediğinizi varsayarak, uygulamanızı tutacak bir dizin oluşturun (buna “ markdown-api ” diyelim) ve bu dizine geçin:

 $ mkdir markdown-api $ cd markdown-api

Uygulamanız için bir package.json dosyası oluşturmak için npm init komutunu kullanın. Bu komut, uygulamanızın adı ve sürümü gibi bir dizi şeyi ister.

Şimdilik, çoğu için varsayılanları kabul etmek için Enter'a basmanız yeterlidir. Varsayılan giriş noktası dosyasını index.js olarak kullandım, ancak tercihlerinize bağlı olarak app.js veya başka bir dosya deneyebilirsiniz.

Şimdi Express'i markdown-api dizinine kurun ve bağımlılıklar listesine kaydedin:

 $ npm install express --save

Geçerli dizinde ( markdown-api ) bir index.js dosyası oluşturun ve Express çerçevesinin düzgün şekilde kurulup kurulmadığını test etmek için aşağıdaki kodu ekleyin:

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

Şimdi test dosyasının düzgün çalışıp çalışmadığını kontrol etmek için https://localhost:3000 URL'sine gidin. Her şey yolundaysa, bir Merhaba Dünya göreceğiz!' tarayıcıda selamlama ve Markdown'ı HTML'ye dönüştürmek için bir temel API oluşturmaya devam edebiliriz.

2. Aşama: Bir Temel API Oluşturma

API'mizin birincil amacı, Markdown sözdizimindeki metni HTML'ye dönüştürmek olacaktır. API'nin iki uç noktası olacaktır:

• /login
• /convert

login bitiş noktası, uygulamanın geçerli isteklerin kimliğini doğrulamasına izin verirken, convert bitiş noktası Markdown'ı (belli ki) HTML'ye dönüştürür.

İki uç noktayı çağırmak için temel API kodu aşağıdadır. login çağrısı yalnızca "Kimliği Doğrulanmış" bir dize döndürürken, convert çağrısı uygulamaya gönderdiğiniz Markdown içeriğini döndürür. Ev yöntemi yalnızca bir 'Merhaba Dünya!' döndürür. sicim.

 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"); });

Uygulamalara gelen istekleri ayrıştırmayı kolaylaştırmak için body-parser ara katman yazılımını kullanıyoruz. Ara yazılım, gelen tüm istekleri req.body özelliği altında sizin için kullanılabilir hale getirecektir. Ek ara katman yazılımı olmadan yapabilirsiniz ancak bunu eklemek, gelen çeşitli istek parametrelerini ayrıştırmayı çok daha kolaylaştırır.

body-parser parser'ı sadece npm kullanarak kurabilirsiniz:

 $ npm install body-parser

Artık kukla saplama işlevlerimizi yerine getirdiğimize göre, aynısını test etmek için Postman'ı kullanacağız. İlk önce Postman'a kısa bir genel bakışla başlayalım.

Postacıya Genel Bakış

Postman, bir tarayıcı içinden veya bir masaüstü uygulaması indirerek API uç noktaları oluşturmayı, değiştirmeyi ve test etmeyi kolaylaştıran bir API geliştirme aracıdır (tarayıcı sürümü artık kullanımdan kaldırılmıştır). GET, POST, PUT, PATCH gibi çeşitli HTTP istekleri yapma yeteneğine sahiptir. Windows, macOS ve Linux için kullanılabilir.

İşte Postacı'nın arayüzünün bir tadı:

Bir API uç noktasını sorgulamak için aşağıdaki adımları uygulamanız gerekir:

1. Sorgulamak istediğiniz URL'yi üst bölümdeki URL çubuğuna girin;
2. İsteği göndermek için URL çubuğunun solundaki HTTP yöntemini seçin;
3. 'Gönder' düğmesine tıklayın.

Postacı daha sonra talebi uygulamaya gönderir, tüm yanıtları alır ve alt pencerede görüntüler. Bu, Postacı aracının nasıl kullanılacağına ilişkin temel mekanizmadır. Bizim uygulamamızda, aşağıdaki bölümlerde açıklanacak olan isteğe başka parametreler de eklememiz gerekecek.

Postacıyı Kullanma

Artık Postman'e genel bir bakış gördüğümüze göre, onu uygulamamız için kullanmaya devam edelim.

markdown-api uygulamanızı komut satırından başlatın:

 $ node index.js

Temel API kodunu test etmek için Postman'den uygulamaya API çağrıları yapıyoruz. Uygulamaya dönüştürülecek metni iletmek için POST yöntemini kullandığımızı unutmayın.

Şu anda uygulama, content POST parametresi aracılığıyla dönüştürülecek Markdown içeriğini kabul ediyor. Bunu, URL kodlu bir biçim olarak iletiyoruz. Şu anda uygulama, dizeyi kelimesi kelimesine bir JSON biçiminde döndürür - ilk alan her zaman dize işaretlemesini markdown ve ikinci alan dönüştürülen metni döndürür. Daha sonra Markdown işleme kodunu eklediğimizde dönüştürülen metni döndürür.

Aşama 3: Markdown Converter Ekleme

Şimdi oluşturulan uygulama iskelesiyle, Markdown'ı HTML'ye dönüştürmek için kullanacağımız Showdown JavaScript kitaplığına bakabiliriz. Showdown, JavaScript'te yazılmış, Markdown'ı HTML'ye ve geri dönüştürmenize izin veren iki yönlü bir Markdown'dan HTML'ye dönüştürücüdür.

Paketi npm kullanarak kurun:

 $ npm install showdown

İskeleye gerekli hesap açma kodunu ekledikten sonra aşağıdaki sonucu alıyoruz:

 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"); });

Ana dönüştürücü kodu, çıkarıldığı ve aşağıda gösterildiği gibi /convert uç noktasındadır. Bu, gönderdiğiniz Markdown metnini bir HTML sürümüne dönüştürür ve onu bir JSON belgesi olarak döndürür.

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

Dönüştürmeyi yapan yöntem, converter.makeHtml(text) yöntemidir. Aşağıdaki formatta setOption yöntemini kullanarak Markdown dönüşümü için çeşitli seçenekler ayarlayabiliriz:

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

Örneğin, belirli bir URL'yi herhangi bir işaretleme olmadan otomatik olarak eklemek ve bağlamak için bir seçenek ayarlayabiliriz.

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

Postacı örneğinde olduğu gibi, uygulamaya simplifiedAutoLink bir dize ( Google home https://www.google.com/ gibi) iletirsek, simulatedAutoLink etkinleştirilmişse aşağıdaki dizeyi döndürür:

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

Seçenek olmadan, aynı sonuçları elde etmek için işaretleme bilgisi eklememiz gerekecek:

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

Markdown'ın nasıl işlendiğini değiştirmek için birçok seçenek vardır. Tam bir liste Showdown web sitesinde bulunabilir.

Artık tek bir uç nokta ile çalışan bir Markdown-HTML dönüştürücümüz var. Daha ileri gidelim ve uygulamaya sahip olmak için kimlik doğrulama ekleyelim.

4. Aşama: Pasaport Kullanarak API Kimlik Doğrulaması Ekleme

Uygun kimlik doğrulama olmadan uygulama API'nizi dış dünyaya göstermek, kullanıcıları herhangi bir kısıtlama olmaksızın API uç noktanızı sorgulamaya teşvik edecektir. Bu, vicdansız unsurları API'nizi kötüye kullanmaya davet edecek ve ayrıca sunucunuza denetlenmeyen istekler yükleyecektir. Bunu azaltmak için uygun bir kimlik doğrulama mekanizması eklemeliyiz.

Uygulamamıza kimlik doğrulama eklemek için Passport paketini kullanacağız. Tıpkı daha önce karşılaştığımız body-parser ara yazılımı gibi, Passport da Node.js için bir kimlik doğrulama ara yazılımıdır. Passport'u kullanmamızın nedeni, kullanıcıya belirli bir mekanizmayı seçme esnekliği veren çeşitli kimlik doğrulama mekanizmalarına (kullanıcı adı ve şifre, Facebook, Twitter vb.) sahip olmasıdır. Bir Passport ara yazılımı, fazla kod değiştirmeden herhangi bir Express uygulamasına kolayca bırakılabilir.

Paketi npm kullanarak kurun.

 $ npm install passport

Kimlik doğrulama için daha sonra açıklanacak olan local stratejiyi de kullanacağız. Öyleyse onu da kurun.

 $ npm install passport-local

Ayrıca, Passport tarafından kullanılan Node.js için JWT(JSON Web Token) kodlama ve kod çözme modülünü de eklemeniz gerekecektir:

 $ npm install jwt-simple

Pasaportta Stratejiler

Passport, istekleri doğrulamak için strateji kavramını kullanır. Stratejiler, isteklerin kimliğini doğrulamanıza izin veren çeşitli yöntemlerdir ve kullanıcı adı ve parola kimlik bilgilerini doğrulama, OAuth (Facebook veya Twitter) kullanarak kimlik doğrulama veya OpenID kullanma gibi basit durumdan değişebilir. İsteklerin kimliğini doğrulamadan önce, bir uygulama tarafından kullanılan strateji yapılandırılmalıdır.

Uygulamamızda, anlaşılması ve kodlanması basit olduğu için basit bir kullanıcı adı ve şifre doğrulama şeması kullanacağız. Şu anda Passport, burada bulunabilecek 300'den fazla stratejiyi desteklemektedir.

Passport'un tasarımı karmaşık görünse de, koddaki uygulaması çok basittir. İşte /convert uç noktamızın kimlik doğrulama için nasıl dekore edildiğini gösteren bir örnek. Göreceğiniz gibi, bir metoda kimlik doğrulama eklemek yeterince basittir.

 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 }) });

Şimdi, dönüştürülecek Markdown dizesi ile birlikte bir kullanıcı adı ve şifre de göndermemiz gerekiyor. Bu, uygulama kullanıcı adımız ve şifremiz ile kontrol edilecek ve doğrulanacaktır. Kimlik doğrulama için yerel bir strateji kullandığımızdan, kimlik bilgileri kodun kendisinde depolanır.

Bu bir güvenlik kabusu gibi görünse de, demo uygulamaları için bu yeterince iyidir. Bu, örneğimizdeki kimlik doğrulama sürecini anlamayı da kolaylaştırır. Bu arada, kullanılan yaygın bir güvenlik yöntemi, kimlik bilgilerini ortam değişkenlerinde saklamaktır. Yine de pek çok kişi bu yöntemle aynı fikirde olmayabilir, ancak bunu nispeten güvenli buluyorum.

Kimlik doğrulama ile tam örnek aşağıda gösterilmiştir.

 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"); });

Kimlik doğrulama eklenmiş olarak dönüştürmeyi gösteren bir Postacı oturumu aşağıda gösterilmiştir.

Burada, bir Markdown sözdiziminden uygun bir HTML ile dönüştürülmüş dizeye sahip olduğumuzu görebiliriz. Yalnızca tek bir Markdown satırını dönüştürmeyi talep etmemize rağmen, API daha büyük miktarda metni dönüştürebilir.

Bu, Node.js ve Express kullanarak bir API uç noktası oluşturmaya yönelik kısa girişimimizi tamamlıyor. API oluşturma karmaşık bir konudur ve bir tane oluştururken farkında olmanız gereken daha ince nüanslar vardır, ne yazık ki burada buna zamanımız yok ama belki de gelecekteki makalelerde ele alacağız.

API'mize Başka Bir Uygulamadan Erişmek

Artık bir API oluşturduğumuza göre, API'ye nasıl erişilebileceğini size gösterecek küçük bir Node.js betiği oluşturabiliriz. Örneğimiz için, HTTP istekleri yapmak için basit bir yol sağlayan request npm paketini kurmamız gerekecek. (Muhtemelen bunu zaten yüklemiş olacaksınız.)

 $ npm install request --save

API'mize istek göndermek ve yanıt almak için örnek kod aşağıda verilmiştir. Gördüğünüz gibi request paketi konuyu oldukça basitleştiriyor. Dönüştürülecek işaretleme, textToConvert değişkenindedir.

Aşağıdaki betiği çalıştırmadan önce, daha önce oluşturduğumuz API uygulamasının zaten çalıştığından emin olun. Aşağıdaki betiği başka bir komut penceresinde çalıştırın.

Not : textToConvert değişkeni için birden çok JavaScript satırını yaymak için (back-tick) işaretini kullanıyoruz (back-tick) Bu tek bir alıntı değildir.

 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)); });

API'mize bir POST isteği yaptığımızda, kimlik bilgileriyle birlikte dönüştürülecek Markdown metnini sağlarız. Yanlış kimlik bilgileri sağlarsak, bir hata mesajı ile karşılaşacağız.

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

Doğru şekilde yetkilendirilmiş bir istek için, yukarıdaki örnek Markdown aşağıdakine dönüştürülecektir:

 [ '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>` ]

Markdown'ı burada sabit kodlamış olmamıza rağmen, metin diğer çeşitli kaynaklardan gelebilir - dosya, web formları vb. Talep süreci aynı kalır.

İsteği application/json içerik türü olarak gönderdiğimiz için; gövdeyi json kullanarak kodlamamız gerekiyor, dolayısıyla JSON.stringify işlev çağrısı. Gördüğünüz gibi, test etmek veya API uygulamasını test etmek çok küçük bir örnek alıyor.

Çözüm

Bu makalede, bir API uç noktası oluşturmak için Node,js ve Express çerçevesinin nasıl kullanılacağını öğrenmek amacıyla bir eğitime başladık. Amaçsız bir kukla uygulama oluşturmak yerine, Markdown sözdizimini HTML'ye dönüştüren ve yararlı bir bağlamda sabitleyen veya öğrenen bir API oluşturmaya karar verdik. Bu arada API uç noktamıza kimlik doğrulama ekledik ve ayrıca Postman kullanarak uygulama uç noktamızı test etmenin yollarını gördük.