Einfache REST API mit NodeJS und Express erstellen

In diesem Beitrag meiner kleinen NodeJS Serie, möchte ich zeigen wie man man mit NodeJS und Express eine einfache REST API erstellt. Ziel wird es sein, über eine URL-Parameter einen Suchbegriff an einen Server-Endpoint zu übermitteln. Dieser Antwortet im Anschluss mit GIF-Memes als JSON Objekt.

Vorbereitung

Um später nach GIF-Memes suchen zu können, müssen wir einen Developer-Account bei Giphy anlegen.

Für den API-Key einfach eine „App erstellen“ und bestätigen, dass die App nicht zu kommerziellen Zwecken genutzt wird.

Wir erstellen zunächst einen Projekt-Ordner. In meinem Fall giphy-app. Wir navigieren über das Terminal in unseren neu erstellen Ordner und initialisieren ein neues Node Package mit

npm init -y

Der -y Flag setzt alle Einstellungen auf Standard-Werte, wie z.B. die Versionsnummer unserer App. Neben dem Express Framework, brauchen wir noch zusätzlich das Request Package.

npm install request

Für unseren Endpoint erstellen wir die Datei app.js in unserem Ordner.

Web Server einrichten & Routing

Wie eingangs bereits erwähnt, wird in diesem Beitrag nicht behandelt, wie ein Webserver mit NodeJS und Express erstellt wird. Die Anleitung dazu findet sich hier.

Noch bevor wir uns um das Routing kümmern können, müssen wir die Packages importieren und Express initalisieren.

const request = require('request') 
const express = require('express') 
const app = express()

Damit ist der langweilige Part erledigt. Jetzt können wir dem Server beibringen wie er sich verhalten soll, wenn wir http://localhost:3000 aufrufen – dem Routing. In diesem Beispiel nutzen wir die GET Methode um zwischen Client und Server zu kommunizieren. Express bietet uns dazu eine eigene Funktion die wir nutzen können.

app.get('/', (req, res) => { res.send('Hello World') })

Die Funktion empfängt zwei Parameter. Der Erste die Route als String und der Zweite eine Callback-Funktion mit den Variablen request und response. In dem Code-Beispiel oben, senden wir beim Aufruf der „Startseite“ einen String mit dem Inhalt „Hello World“ an den Client des Nutzers zurück.

Wir können das sogar jetzt schon testen indem wir noch folgenden Code ergänzen:

app.listen(3000, () => { console.log('Server is up!') })

um den Web-Server starten zu können. Über das Terminal starten wir nun die App.

node app.js

Über den Aufruf von http://localhost:3000 sollten wir jetzt die Nachricht „Hello World“ sehen.

Perfekt! Der Server läuft.

URL-Parameter Übergabe

Nur weil der Server Antwortet, macht ihn das noch zu keiner REST API. Wir wollen schließlich eine spezifische Anfrage stellen, auf die wir auch eine individuelle Antwort bekommen sollen. In diesem konkreten Beispiel lösen wir das mit einem URL-Parameter.

http://localhost:3000/?search=cats

Das Keyword search wird ergänzt durch den Wert cats. Die Herausforderung: Der Server muss verstehen auf den spezifischen Paramater search zu reagieren um den Wert cats als Suchbegriff weiterverarbeiten zu können.

Die Lösung: das Routing.

Ähnlich wie bereits oben bei der Erstkonfiguration unseres Webservers, nutzen wir das Routing um den Parameter auszulesen.

app.get('/', (req, res) => { res.send(req.query.search) })

Der wesentliche Unterschied ist allerdings, dass wir nun die request Variable des Callbacks verwenden um den Query-String (URL-Parameter) auszulesen. Dabei greifen wir auf die Methode query zurück, die nach unserem Key sucht um uns den Wert zurückzugeben, in diesem Fall cats.

Nach eine Neustart des Webservers können wir jetzt unsere Anfrage mit einem Parameter stellen.

Der Server antwortet wie erwartet mit dem Wert unserer Suchanfrage – großartig!

Giphy API verwenden

Um Ergebnisse für unsere Suchanfrage zu bekommen, verwenden wir die Giphy API. Voraussetzung, wie eingangs erwähnt, ist ein API Key, den man kostenlos nach Registrierung bekommt. Damit können wir Suchanfragen stellen. Weitere Informationen zu den APIs von Giphy gibt es hier.

http://api.giphy.com/v1/gifs/search?q=funny+cat&api_key=YOUR_API_KEY

Für unsere Zwecke reicht die einfache Search-API. Diese gibt uns ein JSON-Object zurück mit 25 GIFs, ebenfalls als JSON-Object.

Mit einem gültigen API Key, können wir eine Suche direkt über den Browser ausführen und bekommen wie erwartet die Informationen zu den GIFs als JSON.

NodeJS Request

Die Herausforderung ist es jetzt diesen Request an die Giphy-Server, statt via Browser, durch unseren Web-Server ausführen zu lassen. Dazu verwenden wir das Request Package, welches wir zur Vorbereitung bereits installiert und initialisiert haben.

const url = 'http://api.giphy.com/v1/gifs/search?q=funny+cat&api_key=YOUR_API_KEY' 

request({url: url, json: true}, (error, {body}) => { res.send(body) })

"request" erwartet zwei Parameter, der Erste als Objekt die URL sowie die Darstellungsoption (hier: json parsing). Der Zweite, eine Callback-Funktion mit zwei Parametern. Der body gibt uns das gesamte Objekt zurück welches bei erfolgreicher Datenübermittlung des Giphy-Servers zur Verfügung steht. In unserem konkreten Beispiel, senden wir es zurück an den Anfragesteller unseres Webservers. Dazu müssen wir allerdings den Code in das Routing integrieren.

app.get('/', (req, res) => { 
     const url = 'http://api.giphy.com/v1/gifs/search?q=funny+cat&api_key=YOUR_API_KEY' 
     request({url: url, json: true}, (error, {body}) => { 	res.send(body) }) 
})

Aktuell ist unsere Suchanfrage allerdings statisch und wir bekommen beim Aufruf von localhost:3000 nur Ergebnisse für „Funny Cat“. Deshalb müssen wir das Routing anpassen und bedienen uns dazu dessen, was wir bei der URL-Parameter-Übergabe gelernt haben.

app.get('/', (req, res) => { 
    if (!req.query.search) { 
        return res.send('Please provide a search string...') 
    }
    const url = 'http://api.giphy.com/v1/gifs/search?q=' 
    + encodeURIComponent(req.query.search) 
    + '&YOUR_API_KEY' 
    request( { url, json: true }, (error, {body}) => { 
        if (error) { return res.send('Unable to connect.') 
    } res.send(body) }) 
})

Wir prüfen auf das Vorhandensein des Keys search und damit dessen Wertes, welcher unseren Suchbegriff darstellt. Diesen integrieren wir nun in die URL für die giphy-Anfrage. Im Anschluss wird via request die Anfrage gestellt. Bei erfolgreicher Übermittlung, senden wir den body, also das JSON Objekt von Giphy an den Client des Nutzers zurück.

Abschließend muss nur noch getestet werden.

Hervorragend! Damit können wir nun mittels unseres Webservers nach GIFs suchen und Anfragen über die GET Methode via URL Parameter stellen. Der Server nutzt die API von Giphy, leitet die Anfrage weiter, verarbeitet diese und gibt uns 25 GIFs als JSON-Objects zurück.

Was hat das mit REST APIs zu tun?

Ganz einfach: Das obige Beispiel ist die einfachste Form einer REST API. REST steht für REpresentational State Transfer. Was bedeutet, dass Client und Server zustandslos miteinander kommunizieren. Das heißt, dass jede Anfrage des Clients alle nötigen Informationen für den Server bereitstellen muss, damit dieser die Anfrage verarbeiten kann. Da nur Daten ausgetauscht werden, bieten REST Schnittstellen die Möglichkeit in jeden belieben Client implementiert zu werden, der das HTTP Protokoll unterstützt.

Wie im Screenshot zu sehen, können mit einem beliebigen Programm (hier: Postman) unsere Anfrage stellen und bekommen ebenfalls unseren Datensatz zurück. Das bietet die Möglichkeit unsere REST API z.B. Apps oder anderen IoT Geräte/Anwendungen zur Verfügung zu stellen.

Abschließend der gesamte Code zusammengefasst.

const request = require('request')
const express = require('express')
const app = express()
app.get('/', (req, res) => {
    if (!req.query.search) {
        return res.send('Please provide a search string...')
    }
    
    const url = 'http://api.giphy.com/v1/gifs/search?q=' 
    + encodeURIComponent(req.query.search) 
    + '&api_key=YOUR_API_KEY'
    request( { url, json: true }, (error, {body}) => {
        if (error) {
            return res.send('Unable to connect.')
        }
        res.send(body)
    })
})
app.listen(3000, () => {
    console.log('Server is up!')
})