Advertisement
  1. Code
  2. Node.js

RESTful API Design mit NodeJS und Restify

by
Read Time:12 minsLanguages:

German (Deutsch) translation by Władysław Łucyszyn (you can also view the original English article)

Final product imageFinal product imageFinal product image
What You'll Be Creating

Die RESTful-API besteht aus zwei Hauptkonzepten: Ressource und Darstellung. Ressource kann ein beliebiges Objekt sein, das mit Daten verknüpft oder mit einem URI identifiziert ist (mehr als ein URI kann auf dieselbe Ressource verweisen) und mit HTTP-Methoden betrieben werden. Die Darstellung ist die Art und Weise, wie Sie die Ressource anzeigen. In diesem Tutorial werden einige theoretische Informationen zum RESTful-API-Design behandelt und eine beispielhafte Blogging-Anwendungs-API mithilfe von NodeJS implementiert.

Ressource

Die Auswahl der richtigen Ressourcen für eine RESTful-API ist ein wichtiger Abschnitt beim Entwerfen. Zunächst müssen Sie Ihre Geschäftsdomäne analysieren und dann entscheiden, wie viele und welche Ressourcen verwendet werden, die für Ihre Geschäftsanforderungen relevant sind. Wenn Sie eine Blogging-API entwerfen, werden Sie wahrscheinlich Artikel, Benutzer und Kommentar verwenden. Dies sind die Ressourcennamen, und die damit verbundenen Daten sind die Ressource selbst:

Ressourcenverben

Sie können mit einer Ressourcenoperation fortfahren, nachdem Sie sich für die erforderlichen Ressourcen entschieden haben. Die Operation bezieht sich hier auf HTTP-Methoden. Um beispielsweise einen Artikel zu erstellen, können Sie folgende Anfrage stellen:

Auf die gleiche Weise können Sie einen vorhandenen Artikel anzeigen, indem Sie die folgende Anforderung ausgeben:

Was ist mit der Aktualisierung eines vorhandenen Artikels? Ich kann hören, dass Sie sagen:

Ich kann eine weitere POST-Anfrage an /articles/update/123456789012 mit der Nutzlast stellen.

Vielleicht vorzuziehen, aber die URI wird immer komplexer. Wie bereits erwähnt, können Operationen auf HTTP-Methoden verweisen. Dies bedeutet, dass Sie den Aktualisierung-Vorgang in der HTTP-Methode angeben, anstatt ihn in den URI einzufügen. Beispielsweise:

In diesem Beispiel sehen Sie übrigens Tags und Kategoriefelder. Dies müssen keine Pflichtfelder sein. Sie können sie leer lassen und in Zukunft festlegen.

Manchmal müssen Sie einen Artikel löschen, wenn er veraltet ist. In diesem Fall können Sie eine DELETE HTTP-Anforderung an /articles/123456789012 verwenden.

HTTP-Methoden sind Standardkonzepte. Wenn Sie sie als Operation verwenden, verfügen Sie über einfache URIs. Diese einfache API hilft Ihnen dabei, zufriedene Kunden zu gewinnen.

Was ist, wenn Sie einen Kommentar zu einem Artikel einfügen möchten? Sie können den Artikel auswählen und dem ausgewählten Artikel einen neuen Kommentar hinzufügen. Mit dieser Anweisung können Sie die folgende Anforderung verwenden:

Die obige Form der Ressource wird als Unterressource bezeichnet. Kommentar ist eine Unterressource des Artikels. Die oben genannten Kommentar-Nutzdaten werden als untergeordnetes Element des Artikels in die Datenbank eingefügt. Manchmal bezieht sich ein anderer URI auf dieselbe Ressource. Um beispielsweise einen bestimmten Kommentar anzuzeigen, können Sie Folgendes verwenden:

oder:

Versionierung

Im Allgemeinen ändern sich API-Funktionen häufig, um den Verbrauchern neue Funktionen bereitzustellen. In diesem Fall können zwei Versionen derselben API gleichzeitig vorhanden sein. Um diese beiden Funktionen zu trennen, können Sie die Versionierung verwenden. Es gibt zwei Arten der Versionierung

  1. Version in URI: Sie können die Versionsnummer in der URI angeben. Zum Beispiel /v1.1/articles/123456789012.
  2. Version im Header: Geben Sie die Versionsnummer im Header an und ändern Sie niemals den URI. Beispielsweise:

Tatsächlich ändert die Version nur die Darstellung der Ressource, nicht das Konzept der Ressource. Sie müssen die URI-Struktur also nicht ändern. In Version 1.1 wurde dem Artikel möglicherweise ein neues Feld hinzugefügt. Es wird jedoch weiterhin ein Artikel zurückgegeben. Bei der zweiten Option ist der URI immer noch einfach und Verbraucher müssen ihren URI in clientseitigen Implementierungen nicht ändern.

Es ist wichtig, eine Strategie für Situationen zu entwerfen, in denen der Verbraucher keine Versionsnummer angibt. Sie können einen Fehler auslösen, wenn die Version nicht angegeben ist, oder Sie können eine Antwort zurückgeben, indem Sie die erste Version verwenden. Wenn Sie standardmäßig die neueste stabile Version verwenden, können Verbraucher viele Fehler bei ihren clientseitigen Implementierungen erhalten.

Darstellung

Die Darstellung ist die Art und Weise, wie eine API die Ressource anzeigt. Wenn Sie einen API-Endpunkt aufrufen, erhalten Sie eine Ressource zurück. Diese Ressource kann in einem beliebigen Format wie XML, JSON usw. vorliegen. JSON ist vorzuziehen, wenn Sie eine neue API entwerfen. Wenn Sie jedoch eine vorhandene API aktualisieren, die zum Zurückgeben einer XML-Antwort verwendet wurde, können Sie eine andere Version für eine JSON-Antwort bereitstellen.

Das sind genug theoretische Informationen zum RESTful API-Design. Lassen Sie uns einen Blick auf die reale Nutzung werfen, indem wir eine Blogging-API mit Restify entwerfen und implementieren.

Blogging REST API

Design

Um eine RESTful-API zu entwerfen, müssen wir die Geschäftsdomäne analysieren. Dann können wir unsere Ressourcen definieren. In einer Blogging-API benötigen wir:

  • Artikel erstellen, aktualisieren, löschen, anzeigen
  • Erstellen Sie einen Kommentar für einen bestimmten Artikel, Aktualisieren, Löschen, Anzeigen, Kommentieren
  • Benutzer erstellen, aktualisieren, löschen, anzeigen

In dieser API werde ich nicht beschreiben, wie ein Benutzer authentifiziert wird, um einen Artikel oder Kommentar zu erstellen. Informationen zum Authentifizierungsteil finden Sie im Tutorial Token-basierte Authentifizierung mit AngularJS und NodeJS.

Unsere Ressourcennamen sind fertig. Ressourcenoperationen sind einfach CRUD. In der folgenden Tabelle finden Sie eine allgemeine Darstellung der API.

Ressourcenname HTTP-Verben HTTP-Methoden
Artikel Artikel erstellenArtikel aktualisierenArtikel löschenArtikel anzeigen POST /articles mit PayloadPUT /articles/123 mit PayloadDELETE /articles/123GET /article/123
Kommentar Kommentar erstellenComent aktualisierenKommentar löschenKommentar anzeigen POST /articles/123/comments mit PayloadPUT /comments/123 mit PayloadDELETE /comments/123GET /comments/123
Benutzer Benutzer erstellenBenutzer aktualisierenBenutzer löschenBenutzer anzeigen POST /users mit PayloadPUT /users/123 mit PayloadDELETE /users/123GET /users/123

Projektaufbau

In diesem Projekt werden wir NodeJS mit Restify verwenden. Die Ressourcen werden in der MongoDB-Datenbank gespeichert. Zunächst können wir Ressourcen in Restify als Modelle definieren.

Artikel

Kommentar

Benutzer

Für die Benutzerressource wird keine Operation ausgeführt. Wir gehen davon aus, dass wir den aktuellen Benutzer bereits kennen, der Artikel oder Kommentare bearbeiten kann.

Sie können fragen, woher dieses Mongoose-Modul kommt. Es ist das beliebteste ORM-Framework für MongoDB, das als NodeJS-Modul geschrieben wurde. Dieses Modul ist im Projekt in einer anderen Konfigurationsdatei enthalten.

Jetzt können wir unsere HTTP-Verben für die oben genannten Ressourcen definieren. Sie können Folgendes sehen:

In diesem Codeausschnitt werden zunächst die Controller-Dateien, die Controller-Methoden enthalten, iteriert und alle Controller initialisiert, um eine bestimmte Anforderung an den URI auszuführen. Danach werden URIs für bestimmte Operationen für grundlegende CRUD-Operationen definiert. Es gibt auch eine Versionierung für eine der Operationen zu Artikel.

Wenn Sie beispielsweise die Version 2 im Header "Accept-Version" angeben, wird viewArticle_v2 ausgeführt. viewArticle und viewArticle_v2 erledigen beide den gleichen Job und zeigen die Ressource an, aber sie zeigen die Artikelressource in einem anderen Format an, wie Sie im title-Feld unten sehen können. Schließlich wird der Server an einem bestimmten Port gestartet und einige Fehlerberichtsprüfungen werden angewendet. Wir können mit Controller-Methoden für HTTP-Operationen an Ressourcen fortfahren.

article.js

Eine Erklärung der grundlegenden CRUD-Operationen auf der Mungoseite finden Sie unten:

  • createArticle: Dies ist eine einfache Speicher-Operation für articleModel, die vom Anforderungshauptteil gesendet wird. Ein neues Modell kann erstellt werden, indem der Anforderungshauptteil als Konstruktor an ein Modell wie var articleModel = new Article(req.body) übergeben wird.
  • viewArticle: Zum Anzeigen von Artikeldetails wird im URL-Parameter eine Artikel-ID benötigt. findOne mit einem ID-Parameter reicht aus, um Artikeldetails zurückzugeben.
  • updateArticle: Die Artikelaktualisierung ist eine einfache Suchabfrage und eine Datenmanipulation für den zurückgegebenen Artikel. Schließlich muss das aktualisierte Modell durch Ausgeben eines save-Befehls in der Datenbank gespeichert werden.
  • deleteArticle: findByIdAndRemove ist der beste Weg, einen Artikel durch Angabe der Artikel-ID zu löschen.

Die oben erwähnten Mongoose-Befehle sind einfach statische Methoden wie das Article-Objekt, das auch eine Referenz des Mongoose-Schemas ist.

comment.js

Wenn Sie eine Anforderung an einen der Ressourcen-URIs senden, wird die im Controller angegebene zugehörige Funktion ausgeführt. Jede Funktion in den Controller-Dateien kann die Objekte req und res verwenden. Die comment-Ressource hier ist eine Unterressource des Artikels. Alle Abfragevorgänge werden über das Artikelmodell ausgeführt, um ein Unterdokument zu finden und die erforderlichen Aktualisierungen vorzunehmen. Wenn Sie jedoch versuchen, eine Kommentarressource anzuzeigen, wird eine angezeigt, auch wenn in MongoDB keine Sammlung vorhanden ist.

Andere Designvorschläge

  • Wählen Sie leicht verständliche Ressourcen aus, um den Verbrauchern eine einfache Verwendung zu ermöglichen.
  • Lassen Sie die Geschäftslogik von den Verbrauchern implementieren. Beispielsweise verfügt die Artikelressource über ein Feld namens slug. Verbraucher müssen dieses Detail nicht an die REST-API senden. Diese Slug-Strategie sollte auf der REST-API-Seite verwaltet werden, um die Kopplung zwischen API und Verbrauchern zu verringern. Verbraucher müssen nur Titeldetails senden, und Sie können den Slug gemäß Ihren Geschäftsanforderungen auf der REST-API-Seite generieren.
  • Implementieren Sie eine Berechtigungsschicht für Ihre API-Endpunkte. Nicht autorisierte Verbraucher können auf eingeschränkte Daten zugreifen, die einem anderen Benutzer gehören. In diesem Lernprogramm wurde die Benutzerressource nicht behandelt. Weitere Informationen zu API-Authentifizierungen finden Sie unter Token-basierte Authentifizierung mit AngularJS und NodeJS.
  • Benutzer-URI anstelle der Abfragezeichenfolge. /articles/123 (gut), /articles?id=123 (schlecht).
  • Behalte den Staat nicht; Verwenden Sie immer die sofortige Eingabe / Ausgabe.
  • Verwenden Sie das Substantiv für Ihre Ressourcen. Sie können HTTP-Methoden verwenden, um Ressourcen zu bearbeiten.

Wenn Sie eine RESTful-API nach diesen Grundregeln entwerfen, verfügen Sie immer über ein flexibles, wartbares und leicht verständliches System.

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.