NodeJS REST API: Routing mit Express in 5 Schritten

Erfahre in diesem Beitrag Schritt-für-Schritt anhand von einfachen Beispielen, wie du Routes und Controller verwenden kannst, um deine API übersichtlicher aufzubauen. Außerdem lernst du wir du deine Endpunkte mit dem kostenlosen Tool Postman testen kannst.

Vorbereitung 🤓

Bevor es los geht, solltest du folgende Punkte für dich abhaken können:

• Du hast ein grobes Verständnis wie APIs funktionieren ✔
• Du kannst etwas NodeJS und Express anfangen oder hast schon mal einen ersten kleinen Webserver damit gebaut ✔

Falls du bisher nicht mit NodeJS oder Express gearbeitet hast, dann empfehle ich dir diesen Beitrag. Gleichzeitig dient der Code aus dem Tutorial als Grundlage für diese Anleitung. Es lohnt sich also reinzuschauen. 😉

APIs und Endpunkte

Vermutlich hast du dich bereits mit (REST) APIs beschäftigt und bist auf den Begriffe "Routing" oder "Routes" gestoßen. An dieser Stelle gehe ich nicht tiefer auf APIs ein, wiederhole aber gerne nochmal kurz ihren Zweck. APIs sind Schnittstelen, die die Kommunikation zwischen mehreren Systemen im Netz ermöglichen.

Auf einem Webserver kann deine API z.B. HTML Dateien bereitstellen, die ein Nutzer abrufen kann um eine Website oder Web App anzuzeigen. APIs stellen also einen oder mehrere Endpunkt(e) bereit, die eine bestimmte Funktion ausüben (in meinem Beispiel ist es das Breitstellen von HTML-Dateien).

Was sind Routes und Controller? 🚏🎮

Damit ein User einen Endpunkt ansprechen kann, muss er wissen wie er oder sie dort "hinkommt". Dafür baucht es Wege oder Routen – auf Englisch also Routes. Sie stellen in erster Linie einen Pfad dar, über welchen wiederum ein Endpunkt einer API angesprochen werden kann.

Außerdem nimmt die Route User-Input entgegen (z.B. Daten aus einem Formular). Sie kann dies verarbeiten und z.B. die Ergebnisse aus der Interaktion mit einer Datenbank bereitstellen. Dieses Handling der User-Anfragen (Requests) werden zwar innerhalb der Route erledigt, haben jedoch einen eigenen Namen – die Controller.

Ziemlich viel Theorie – doch lass' uns das mal anhand von einem Beispiel langsam durchgehen. Dafür erstellst du ein neues NodeJS Projekt. 👇

Schritt 1: Projektstruktur

In diesem Beispiel soll es darum gehen, dass wir dem User via API, Routes und Controllern die Möglichkeiten geben wollen, seine Nutzerdaten abrufen zu können. Die Projektstruktur sieht dafür so aus:

Falls du das Projekt nicht selbst neu anlegen möchtest, dann findest du den fertigen Code inklusive der kompletten Projektstruktur hier auf Github. Es ist übrigens eine Konvention, dass die 'user.js' in den Ordnern 'controllers' und 'routes' beide gleich heißen. Das hilft dir später bei der Übersicht um die Controller den Routes zuordnen zu können.

Schritt 2: Deine erste Route

Wir starten zunächst in der 'index.js'. Du erstellst einen simplen Endpunkt mit der GET-Methode direkt in der Datei. Bei mir sieht das so aus:

app.get('/user/profile', function(req, res) {
    res.send('Dein Profil...')
})

Nice! Deine erste Route ist fertig. 🥳 Das wars schon? Ja und nein– aber dazu später mehr. Checke erst mal ob deine Route bisher korrekt funktioniert. Für eine funktionierende Route sollte deine 'index.js' in etwa so aussehen:

const express = require('express')
const app = express()
app.use(express.json());
const port = process.env.PORT || 3001

app.get('/user/profile', function(req, res) {
    res.send('Dein Profil...')
})

app.listen(port, (err) => {
    if (err) {
        console.log('Error: ', err)
    } else {
        console.log('Server is up on port: ', port)
    }
})

Schritt 3: Testen mit Postman 🧪

Bevor es mit den Routes und Controllern weitergeht, teste zunächst deinen Endpunkt mit dem kostenlosen API-Tool Postman. Gebe dazu einfach deine localhost URL ein. Bei mir sieht das so aus:

Wenn du auf 'send' klickst, solltest du unten im Body-Bereich eine Antwort erhalten. Glückwunsch, dein API-Endpunkt mit der Route 'user/profile' funktioniert! Jetzt geht es darum die Routes in die eigenen Ordnerstruktur auszulagern. Wie das geht, erfährst du im nächsten Schritt.  

Schritt 4: Routes auslagern

In diesem Schritt lagerst du deine Route in die dafür angelegte Dateien 'user.js' im 'routes' Ordner aus. Dafür sollte deine 'user.js' für den Moment so aussehen:

const express = require('express'); //import express
const router  = express.Router(); 


router.get('/user/profile', function(req, res) {
    res.send('Dein Profil...')
})

// export der Router für die Wiederverwendung in der index.js
module.exports = router; 

Nun musst du schauen, dass du die Routes (in diesem Fall erst mal nur eine) in deine 'index.js' importierst. Die Vorarbeit hast du dafür schon gemacht. Nämlich den Export der Routes aus deiner 'user.js'. Der Import in der 'index.js' sieht so aus:

const express = require('express')
const app = express()
app.use(express.json());
const port = process.env.PORT || 3001

// import der Routes
const userRoutes = require('./routes/user');
app.use(userRoutes)

app.listen(port, (err) => {
    if (err) {
        console.log('Error: ', err)
    } else {
        console.log('Server is up on port: ', port)
    }
})

Starte deinen Webserver neu und teste den API-Endpunkt mit Postman. Du solltest jetzt, wie zuvor auch, deine Message über die API zurückbekommen. Hat's geklappt? Gratulation! Du hast deine Route erfolgreich ausgelagert. 🎉

Du bist auf der Zielgeraden! Abschließend wollen wir den Controller auslagern. Das schauen wir uns im finalen Schritt an. 👇

Schritt 5: Controller auslagern

Analog aus dem Step 4, lagerst du nun den Controller in die 'user.js' aus. Achtung: In diesem Fall die 'user.js' in dem 'controller' Ordner.

Vielleicht fragst du dich gerade: "Was ist eigentlich dieser Controller von dem du die ganze Zeit sprichst?" 🤔

Zugegeben, ich hatte die Erklärung am Anfang eher beiläufig gegeben. Deshalb wiederhole ich es gerne nochmal für dich an dieser Stelle:

Mit unserem Router-Beispiel wird es noch klarer – versprochen:

router.get('/user/profile', function(req, res) {
    res.send('Dein Profil...')
})

Der Controller ist hier die Funktion, die als zweiter Parameter übergeben wird, also:

function(req, res) {
    res.send('Dein Profil...')
}

Nachdem du jetzt weißt was der Controller ist, lass ihn uns in die entsprechende 'user.js' auslagern. Das geht so:

// getUserProfile Funktion für die entsprechende Route
const getUserProfile = function (req, res, next) {
    res.send('Dein Profil...')
}

module.exports = { getUserProfile };

Auch hier wirst du feststellen, dass wir die Funktion exportiert haben. Du musst sie jetzt nur noch in deine Route in 'user.js' ('routes' Ordner) importieren und einfügen:

const express = require('express'); //import express
const router  = express.Router(); 
const userController = require('../controllers/user')

router.get('/user/profile', userController.getUserProfile)

// export der Router für die Wiederverwendung in der index.js
module.exports = router; 

Nachdem du die User-Controller importiert hast, kannst du über die Punktnotation auf deine spezifische Controller-Funktion zugreifen und sie als zweiten Parameter an den Router übergeben. Fertig, du hast es geschafft! 🎉👏

Teste abschließend deine Route erneut mit Postman. Den kompletten Code für dieses Projekt findest du übrigens auf Github.

Fazit ✅

Router sind wichtig für die Kommunikation zwischen User (Client) und API-Endpunkt (Server). Die Controller kümmern sich um das Handling der Anfragen und stellen die Antwort bereit.

Sicherlich wirkt das Auslagern der Routes und Controller in eigene Dateien und Ordner etwas over-engineered. In den Beispielen die du kennengelernt hast ist es das sicherlich auch, aber ich kann dir versprechen, je komplexer und länger dein Code wird, desto hilfreicher ist diese Struktur um die Übersicht zu behalten.

Wie geht es weiter?

Falls du bereits ein Projekt mit mehreren Endpunkten und Routes umgesetzt hast, dann bringe mit der neuen Projektstruktur etwas mehr Ordnung  in deinen Code. Vielleicht möchtest du dein Projekt veröffentlichen? Dann empfehle ich dir diesen Beitrag, hier lernst du wie du deine NodeJS App schnell und einfach mit Heroku deployst.

Hat dir dieser Beitrag gefallen? Dann freue mich sehr darüber wenn du ihn teilst. Solltest du Fragen oder Feedback haben, dann schreibe mir auf Twitter @kermsch. Ich freue mich von dir zu hören! 👋 🙂