REST-Interfaces

Literaturhinweis

Tilkov et al.: ​REST und HTTP

Einführung

REST (Representational State Transfer) ist ein architektureller Ansatz des Software Engineerings mit dem Ziel, einheitliche Schnittstellen für verteilte Systeme zu schaffen.

Eine Haupteigenschaft von REST ist die Verwendung von HTTP-Verben zur Kodierung der Methoden (Befehle), die ein Client am Server ausführen kann. Insbesondere sind die Befehle nicht eng an die Objekte gekoppelt, wie das bei vielen herkömmlichen Schnittstellen der Fall ist.

Beispiel: Für das Abrufen eines Objekts vom Typ Student werden in herkömmlichen Schnittstellen häufig Requests der Form

http://mydomain.tld/getStudent.php?id=42

verwendet, wobei die Methode (get) im Namen des Skripts enthalten ist. Die Methode könnte aber beispielsweise ebenso retrieve (...retrieveStudent.php...) oder abrufen (...abrufenStudent.php...) usw. sein. Eine derartige Kodierung der Methode hat keine semantische Bedeutung sondern ist lediglich eine Lesehilfe zum Verständnis der Schnittstelle. Dies wird insbesondere problematisch, wenn für die Skripte keine sprechenden Namen verwendet werden.

In einem REST-Interface würde der URL

http://mydomain.tld/student/42

lauten und es würde die HTTP-Methode GET verwendet werden. Der URL ist aus drei Teilen aufgebaut:

• Adresse der Webanwendung: http://mydomain.tld/
• Objekttyp, auf den sich die Anfrage bezieht: student
• ID des Objekts: 42

Alle REST-Interfaces folgen im Wesentlichen dieser URL-Struktur, die ggf. etwas komplexer sein kann. Mit dieser Form ist aus dem Request eindeutig ableitbar, welches Ziel verfolgt wird. Jedes Objekt wird durch seinen URL weltweit eindeutig identifizierbar. Damit ist die Implementierung von REST-Schnittstellen nah am HTTP-Standard angesiedelt.

CRUD

Der Funktionsumfang vieler verteilter Informationssysteme kann nach dem CRUD-Schema vollständig beschrieben werden:

• Create: Erzeugen von Objekten
• Read: Lesen / Abrufen von Objekten
• Update: Aktualisieren / Ändern von Objekten
• Delete: Löschen von Objekten

Diesen Befehlen werden die HTTP-Methoden

• GET: Read
• POST: Create
• PUT: Update
• DELETE: Delete

zugeordnet.

REST-Interface mit Node.js

Im Folgenden wird ein REST-Interface für Artikel eines Shopsystems auf der Basis von Node.js entwickelt. Als Client zum Testen des Interfaces verwenden wir den Postman Client von Google Chrome.

Das Interface soll die folgenden Anforderungen erfüllen:

• Abruf eines Artikels mit GET /article/id
• Abruf aller Artikel mit GET /article/ (ohne id)
• Erzeugen eines neuen Artikels mit POST /article/
• Ändern eines Artikels mit PUT /article/id
• Löschen eines Artikels mit DELETE /article/id

Das Interface ist in der Datei shopserver.js​ implementiert.

Exkurs: serverseitige Datenhaltung

Grundsätzlich sollten serverseitig Daten stets in einer Datenbank gehalten werden. Für kleine Projekte oder Tests kann es jedoch sinnvoll sein, wenn die gesamten serverseitig verwalteten Daten immer als Objekte im RAM gehalten werden. Diese Objekte können dann einfach als JSON in eine Datei geschrieben und beim Start des Servers aus dieser Datei gelesen werden:

// Artikel im Shop
var articles = [];

// Einlesen aus Datei (falls vorhanden)
// Auf diese Weise lässt sich sehr einfach eine serverseitige Datenhaltung
// für sehr kleine Projekte implementieren.
// __dirname ist das Verzeichnis des aktuell laufenden Skripts
var filename = __dirname + '/articles.json';
//ggf. vorhandene Daten aus Datei einlesen
try {
    var filedata = fs.readFileSync(filename);
    articles = JSON.parse(filedata);
    console.log(articles.length + " Datensätze eingelesen.")
} catch(err) {
    // Datei exisitiert nicht, wir müssen nichts tun
    console.log("Keine Datensätze eingelesen.")
}

Bei der Pfadangabe der Datei ist zu beachten, dass das aktuelle Verzeichnis von der verwendeten Node.js-Instanz abhängig sein kann. Daher sollte die Pfadangabe explizit gemacht werden. Die erfolgt durch Voranstellen des absoluten Pfades zum aktuellen Skript. Der absolute Pfad wird unter Node.js in der Variablen __dirname bereitgestellt:

// __dirname ist das Verzeichnis des aktuell laufenden Skripts
var filename = __dirname + '/articles.json';

Bei jeder Aktualisierung des Arrays wird dieses neu in die Datei geschrieben und kann damit beim nächsten Serverstart wieder geladen werden:

function updateFile() {
    fs.writeFileSync(filename, JSON.stringify(articles));
}

Artikelobjekte

Die Objekte haben die Attribute name, preis und beschreibung:

{
    name: 'Wasserwaage',
    preis: 14.99,
    beschreibung: 'Das Horizontalste seit der Erfindung des Salzsees.'
}

Allgemeine fachliche Informationen aus dem Request lesen

Bevor die eigentliche Unterscheidung des Befehls entsprechend der HTTP-Methode erfolgt, werden der Objekttyp und ggf. die ID des Objekts aus dem Request gelesen:

function serve(req, res) {
    // welches Objekt?
    // Komponenten aus dem URL holen
    var parts = url.parse(req.url, true).path.split("/");
    console.log(parts);
    
    // Ziel des Requests (Objekttyp)
    var target = parts[1];

    // Wurde eine ID mitgeliefert? Wäre das dritte Element des Requests
    var id = -1;
    if (parts.length > 2 && parts[2] !== "") {
        id = parts[2];
    }
    
    // Debug Ausgabe
    console.log('Ziel: ' + target + ' - ID: ' + id);

    // ...
}

Sofern keine ID im Request enthalten ist, wird diese auf -1 gesetzt.

HTTP-Methoden

Alle Anfragen werden von der Laufzeitumgebung an die als Server registrierte Funktion serve weitergeleitet. Dort muss demnach zwischen den verschiedenen Methoden unterschieden werden. Dies kann mit einer switch-case Anweisung erfolgen:

function serve(req, res) {

    // ...

    console.log('Ziel: ' + target + ' - ID: ' + id);


    // Methode auswerten
    switch (req.method) {
    case "GET":
        // Artikel-Objekt(e) angefordert
        // ...
        break;
    case "POST":
        // neues Objekt erzeugen
        // ...
        break;
    case "PUT":
        // Objekt ändern
        // ...
        break;
    case "DELETE":
        // Objekt löschen
        // ...
        break;
    default:
        // Nicht unterstützte HTTP-Methode
        // ...
        break;
    }
}

Im Folgenden werden die in den jeweiligen cases enthaltenen Codesegmente implementiert. Da vorerst nur ein Objekttyp (article) verarbeitet werden soll, ist es nicht notwendig, auf den jeweiligen Typ zu prüfen. Wir gehen also vorerst von freundlichen Clients aus. Die Struktur einer objektspezifischen Implementierung ist weiter unten beschrieben.

Abrufen mit GET

Für GET sollen die folgenden Anforerungen erfüllt werden:

• der URL enthält eine gültige ID: das zugehörige Objekt wird zurückgeliefert
• der URL enthält keine ID: der Server liefert alle Objekte
• der URL enthält eine ungültige ID: der Server antwortet mit dem Statuscode ​404 (Not Found)

case 'GET':
    // Elemente der Antwort initialisieren (happy path)
    var status = 200;
    var returnType = 'application/json';
    var message = '';

    if (id !== -1) {        
        // falls ID vorhanden: Artikel aus Array lesen
        var artIndex = findIndexById(id);
        
        if (artIndex !== -1) {
            // Artikel ausliefern
            message = JSON.stringify(articles[artIndex]);
        } else {
            // nicht gefunden: 404
            status = 404;
            returnType = 'text/plain';
            message = 'Artikel ' + id + ' nicht gefunden';
        }
    } else {
        // keine ID: alle Artikel
        message = JSON.stringify(articles);
    }
    
    // Antwort senden
    res.writeHead(status, {
        'Content-Type': returnType 
    });
    res.write(message);
    res.end();
    
    break;

findIndexById(id)ist eine Hilfsfunktion, welche das Array articles nach einem Artikel mit der übergebenen ID durchsucht und den Index im Array zurückliefert. Eine Implementierung mit einer Map als Datenstruktur und der ID als Schlüssel wäre hier deutlich effizienter, aber auch umfangreicher.

function findIndexById(id) {
    for (var i = 0; i < articles.length; i++) {
        if (articles[i].id == id) {
            return i;
        }
    }
    // Falls es keinen Artikel mit der id gibt
    return -1;
}

Zum Testen der GET-Methode des REST-Interfaces kann die Datei articles.json​ im Projektverzeichnis abgelegt werden. Bei den Tests mit dem Postman Client erhalten wir diese Ergebnisse:

Request:
GET http://localhost:3000/article/2

Ergebnis:
{
    "name": "Bohrmaschine",
    "preis": 75.99,
    "beschreibung": "Bohrt Beton wie Japanpapier.",
    "id": 2
}

----------------------------------------
Request:
GET http://localhost:3000/article

Ergebnis:
[
    {
        "name": "Wasserwaage",
        "preis": 19.99,
        "beschreibung": "Das Horizontalste seit der Erfindung des Salzsees.",
        "id": 1
    },
    {
        "name": "Bohrmaschine",
        "preis": 75.99,
        "beschreibung": "Bohrt Beton wie Japanpapier.",
        "id": 2
    }
]

----------------------------------------
Request:
http://localhost:3000/article/42

Ergebnis (Statuscode 404):
Artikel 42 nicht gefunden

Erzeugen mit POST

Für die Methode POST muss nur eine Funktion implementiert werden: Sobald ein Artikelobjekt angeliefert wird, wird das Objekt an das Array angehängt und das erhaltene Objekt mit der neu vergebenen ID an den Client zurückgesendet. Hier gilt es wieder zu beachten, dass die Daten in Chunks gesendet werden könnten und daher entsprechende Eventhandler implementiert werden müssen:

case 'POST':
    // Objekt erzeugen
    // Zwischenspeicher für Chunks
    var data = '';
    
    // Eventhandler für Chunk
    req.on('data', function(chunk) {
        data = data + chunk.toString();
    });
    
    // Eventhandler für Ende des Requests (alle Chunks eingetroffen)
    req.on('end', function() {
        // Objekt aus dem Request lesen
        var artikel = JSON.parse(data);
        
        // ID für neues Objekt festlegen
        artikel.id = getMaxId() + 1;
        
        // Artikel in das Array schreiben
        articles.push(artikel);
        // lokale Datei aktualisieren
        updateFile();
        
        // Antwort schreiben
        res.writeHead(201, {
            'Content-Type': 'application/json'
        });
        res.write(JSON.stringify(artikel));
        res.end();
    });

    break;

Der Statuscode ​201 (Created) teilt dem Client mit, dass das Objekt erzeugt wurde. Die Funktion getMaxId() durchsucht das Array nach der höchsten ID, um die nächsthöhere ID an den neuen Artikel zu vergeben. Dies ist an dieser Stelle zur Illustration eingefügt. Effizienter wäre es, diese Funktion direkt nach dem Laden der Daten aus der Datei beim Serverstart einmal auszuführen, des Ergebnis in einer globalen Variablen zu speichern und fortan diese globale Variable bei jedem POST-Request zu inkrementieren.

function getMaxId() {
    var max = 0;
    for (var a of articles) {
        if (a.id > max) {
            max = a.id;
        }
    }
    return max;
}

Der Test mit dem Postman Client ergibt:

Request:
POST http://localhost:3000/article

Request-Body:
{"name":"Kombizange","preis":23.00,"beschreibung":"Beißt kräftig zu und hält sicher."}

Ergebnis (Statuscode 201):
{
    "name": "Kombizange",
    "preis": 23,
    "beschreibung": "Beißt kräftig zu und hält sicher.",
    "id": 3
}

Dem Objekt wurde die ID 3 hinzugefügt.

Ändern mit PUT

Das Ändern von Objekten mit PUT erfordert wieder etwas mehr Aufwand, da die vom Client mitgelieferte ID ungültig oder nicht vorhanden sein könnte. Im ersten Fall soll analog zum GET-Request mit 404 geantwortet werden, im zweiten Fall mit dem HTTP-Statuscode ​400 (Bad Request).

Unter bestimmten Umständen muss die ID des Zielobjekts nicht im URL des Requests enthalten sein, nämlich dann, wenn die ID des Objekts Bestandteil des übermittelten JSON ist und vom Server aus dem Objekt gelesen werden kann. In unseren Beispiel ist dies der Fall. Der guten Form halber sollte man die ID jedoch immer im URL einkodieren, weswegen wir bei fehlender ID den Status 400 (Bad Request) zurückliefern.

Diese Anforderungen sollen umgesetzt werden:

• der URL enthält eine gültige ID: das zugehörige Objekt wird mit dem Inhalt des Requests geändert
• der URL enthält eine ungültige ID: der Server antwortet 404 (Not Found)
• der URL enthält keine ID: der Server antwortet 400 (Bad Request)

Wie bei POST werden PUT-Requests ggf. ebenfalls in Chunks gesendet, so dass entsprechende Eventhandler zu implementieren sind:

case 'PUT':
    // Objekt ändern
    // Zwischenspeicher für Chunks
    var data = '';
    
    // Eventhandler für Chunk
    req.on('data', function(chunk) {
        data = data + chunk.toString();
    });
        
    // Eventhandler für Ende des Requests (alle Chunks eingetroffen)
    req.on('end', function() {
        var status = 200;
        var returnType = 'application/json';
        var message = '';

        if (id !== -1) {
            // Artikel ID im Request enthalten
            var artIndex = findIndexById(id);

            if (artIndex !== -1) {
                // Artikel mit der ID existiert: ersetzen
                var artikel = JSON.parse(data);
                articles[artIndex] = artikel;
                updateFile();

                // geänderten Artikel zurückliefern
                message = JSON.stringify(articles[artIndex]);
            } else {
                // nicht gefunden: 404
                status = 404;
                returnType = 'text/plain';
                message = 'Artikel ' + id + ' nicht gefunden';
            }
        } else {
            // Keine ID im Request --> 400: Bad Request
            status = 400;
            returnType = 'text/plain';
            message = 'Fehlerhafter Request: Artikel ID fehlt.';
        }

        // Antwort senden
        res.writeHead(status, {
            'Content-Type': returnType
        });
        res.write(message);
        res.end();
    });

    break;

Die Tests liefern folgende Ergebnisse:

Request:
PUT localhost:3000/article/3

Request-Body:
{"name":"Kombizange","preis":31.99,"beschreibung":"Beißt kräftig zu und hält sicher.","id":3}

Ergebnis:
{
    "name": "Kombizange",
    "preis": 31.99,
    "beschreibung": "Beißt kräftig zu und hält sicher.",
    "id": 3
}

----------------------------------------
Request:
PUT localhost:3000/article

Request-Body:
beliebig

Ergebnis (Statuscode 400):
Fehlerhafter Request: Artikel ID fehlt.

----------------------------------------
Request:
localhost:3000/article/42

Request-Body:
beliebig

Ergebnis (Statuscode 404):
Artikel 42 nicht gefunden

Löschen mit DELETE

Beim Löschen sind ebenfalls drei Fälle abzudecken:

• der URL enthält eine gültige ID: das zugehörige Objekt wird gelöscht
• der URL enthält eine ungültige ID: der Server antwortet 404 (Not Found)
• der URL enthält keine ID: der Server antwortet 400 (Bad Request)

case "DELETE":
    // Objekt löschen
    var status = 200;
    var returnType = 'text/plain';
    var message = '';

    if (id !== -1) {
        // Artikel ID im Request enthalten
        var artIndex = findIndexById(id);

        if (artIndex !== -1) {
            // Artikel mit der ID existiert: löschen
            articles.splice(artIndex, 1);
            updateFile();
            
            message = 'Artikel ' + id + ' gelöscht';
        } else {
            // nicht gefunden: 404
            status = 404;
            message = 'Artikel ' + id + ' nicht gefunden';
        }
    } else {
        // Keine ID im Request --> 400: Bad Request
        status = 400;
        message = 'Fehlerhafter Request: Artikel ID fehlt.';
    }

    // Antwort senden
    res.writeHead(status, {
        'Content-Type': returnType,
    });
    res.write(message);
    res.end();

    break;

Die Tests mit Postman zeigen die folgenden Ergebnisse:

Request:
DELETE localhost:3000/article/3

Ergebnis:
Artikel 3 gelöscht

----------------------------------------
Request:
DELETE localhost:3000/article/

Ergebnis (Statuscode 400):
Fehlerhafter Request: Artikel ID fehlt.

----------------------------------------
Request:
DELETE localhost:3000/article/42

Ergebnis (Statuscode 404):
Artikel 42 nicht gefunden

Nicht unterstützte HTTP-Methoden

Bei den meisten Implementierungen ist es sinnvoll, dass der Client immer eine Antwort erhält, auch wenn eine nicht unterstützte HTTP-Methode verwendet wird. Dafür kann der Statuscode ​405 (Method Not Allowed) zurückgesendet werden. In diesem Fall erwartet der Client den obligatorischen HTTP-Header ​Allow, in welchem die erlaubten Methoden mitgeteilt werden:

default:
    // Nicht unterstützte HTTP-Methode
    // 405: Method Not Allowed
    // Allow-Header MUSS enthalten sein: https://tools.ietf.org/html/rfc7231#section-6.5.5
    res.writeHead(405, {
        'Content-Type': 'text/plain',
        'Allow': 'GET, POST, PUT, DELETE'
    });
    res.write('HTTP-Methode ' + req.method + ' wird nicht unterstützt. Dies ist ein REST-Interface. Bitte nutzen Sie GET, POST, PUT, DELETE.');
    res.end();

    break;

Diese Verwendung von 405 in der beschriebenen Weise ist möglicherweise nicht ganz sauber, da sich der Fehlercode eigentlich darauf bezieht, dass eine bestimmte Ressource (ein Objekt) nicht mit der gewünschten Methode angesprochen werden darf (s. ​RFC7231). Da die Beschränkung auf die CRUD-Befehle in REST-Interfaces generell jedoch für alle Ressourcen gilt, erscheint die Verwendung von 405 auf die dargestellte Weise gerechtfertigt, zumal es an einer besser geeigneten Methode (z. B. Method Unknown oder Method Not Supported) im HTTP-Protokoll mangelt.

Der Test mit Postman ergibt das folgende Ergebnis:

Request:
COPY localhost:3000/article/2

Ergebnis (Statuscode 405):
Headers: Allow --> GET, POST, PUT, DELETE
Body: HTTP-Methode COPY wird nicht unterstützt. Bitte nutzen Sie GET, POST, PUT, DELETE.

Unterstützung verschiedener Objekttypen

Im vorgenannten Beispiel werden ausschließlich Objekte vom Typ Artikel verarbeitet. Daher muss die Variable

// Ziel des Requests (Objekttyp)
var target = parts[1];

nicht ausgewertet werden.

Sofern das REST-Interface - was bei komplexen Systemen durchaus üblich ist - mehrere Objekttypen verarbeiten kann, sind entsprechende Prüfungen einzubauen, welcher Objekttyp durch den Request verarbeitet werden soll. Dabei empfiehlt es sich für eine verbesserte Wartbarkeit, den Code zu entzerren und die diversen Fachlichkeiten in getrennte Funktionen und ggf. getrennte Quellcodedateien auszulagern:

switch (req.method) {
case 'GET':
    switch (target) {
    case 'article':
        handleGetArticle(req, res);
        break;
    case 'customer':
        handleGetCustomer(req, res);
        break;
    case 'payment':
        handleGetPayment(req, res);
        break;
    default:
        // ...
    }
    break;
case 'POST':
    // ...
}