Seit der Einführung von JavaScript-Frameworks Anfang 2010 hat deren Popularität rasant zugenommen. Sie bieten leistungsstarke Architekturen zum Erstellen von flüssigen, reaktionsschnellen und benutzerfreundlichen Webanwendungen. Da immer mehr Menschen mit ihren Mobilgeräten auf digitale Inhalte zugreifen, ist es sinnvoll, native Anwendungen für Ihre Website zu erstellen.

Drupal hat das Potenzial dieses Marktes erkannt und die Unterstützung für das Erstellen von RESTful APIs in den Core aufgenommen. Die RESTful Web Services des Drupal-Kerns bieten jedoch keine sehr robuste Out-of-the-Box-Lösung. Sie müssen alle Ressourcen aktivieren, die Endpunkte, Verben und Authentifizierungsmechanismen konfigurieren und Ansichten mit REST-Export erstellen, um die gewünschte Lösung zu erstellen.

Die RESTful Web Services des Drupal-Kerns bieten keine sehr robuste Out-of-the-Box-Lösung.

Aber selbst dann folgen die auf diese Weise erstellten APIs nicht unbedingt allgemein anerkannten Richtlinien oder Spezifikationen wie JSON API. Sie können jederzeit benutzerdefinierte Logik schreiben, aber zum Glück gibt es dafür ein Contributed-Modul. Bevor wir verstehen, wie sich dieses Modul als robuste Lösung zum Erstellen entkoppelter Anwendungen erweist, wollen wir einige Grundlagen klären.

Was ist eine API?

Im Zusammenhang mit Webservices ist eine API eine Vereinbarung oder ein Vertrag über Anfrage und Antwort zwischen dem Server (Anbieter) und dem Client (Verbraucher) zum Zweck des Datenaustauschs. Sie ist das Element, das das Frontend und das Backend verbindet. Sie definiert, auf welche Ressourcen zugegriffen werden kann, wer auf sie zugreifen kann und wie auf sie zugegriffen werden kann.

Was ist JSON?

JavaScript Object Notation (JSON) ist das gebräuchlichste Datenformat für den Datenaustausch über Webservices. Es hat XML aufgrund seiner schlanken Natur weitgehend ersetzt. Es ist für Menschen leichter zu lesen und für Maschinen leichter zu parsen. Es wird von fast jeder modernen Programmiersprache und jedem Framework unterstützt.

JSON-API-Spezifikationen – Was und warum sollten Sie deren Implementierung in Betracht ziehen?

Die JSON-API-Spezifikationen sind eine Reihe von Standards und Konventionen, die beschreiben, wie die APIs von den Servern bereitgestellt und von den Clients zum Austausch von Daten im JSON-Format konsumiert werden sollten. Zu den wichtigsten Vorteilen der Implementierung dieser Spezifikationen gehören:

• Konsistenz
  Die Frontend-Entwickler erwarten eine konsistente Struktur und ein konsistentes Verhalten von den APIs, während sie diese zum Erstellen der Anwendungen verwenden.
   
• Weitgehend akzeptiert und unterstützt
  Die Spezifikationen sind weitgehend akzeptiert und Implementierungen von Client-Bibliotheken sind für fast jede Programmiersprache und jedes Framework zu finden.
   
• Effizienz
  Die Spezifikation ist so konzipiert, dass die Anzahl der Anfragen und die Größe der Daten auf ein Minimum reduziert werden.
   
• Produktivität
  Es gibt zahlreiche Möglichkeiten, eine API zu entwerfen, und als Entwickler werden Sie sich oft in einer Auseinandersetzung darüber befinden, welche Best Practices oder Konventionen zum Erstellen einer API gelten. Indem Sie diese Reihe von Standards befolgen, können Sie dies vermeiden und sich auf das Erstellen der Anwendung konzentrieren. 

Nachdem wir nun die Grundlagen verstanden haben, wollen wir sehen, wie das JSON-API-Modul beim Erstellen einer Headless-Website in Drupal hilft.

JSON-API-Spezifikationen – Was und warum sind sie wichtig?

Herunterladen und Installieren des JSON-API-Moduls

Das Modul hat eine Abhängigkeit vom Serialisierungsmodul. Aktivieren Sie es daher zuerst und laden Sie dann JSON API mit einer der folgenden Methoden herunter und installieren Sie es:

Verwenden von Drush

$ drush en serialization -y

$ drush dl jsonapi && drush en jsonapi -y

Verwenden der Drupal-Konsole  

$ drupal module:install serialization
$ drupal module:download jsonapi && drupal module:install jsonapi

Verwenden der Benutzeroberfläche

• Navigieren Sie zu Verwalten → Erweitern → Neues Modul installieren und geben Sie die .tar.gz- oder .zip-URL des Moduls ein und klicken Sie auf Installieren.
• Sobald der Downloader den Download abgeschlossen hat, klicken Sie auf „Neu hinzugefügte Module aktivieren“.
• Wählen Sie das Serialisierungs- und das JSON-API-Modul unter dem Web Services-Paket aus und klicken Sie auf „Installieren“.

Wie hilft JSON API?

Das Modul bietet eine Implementierung der oben genannten Spezifikationen für Drupal. Im Folgenden sind die Funktionen der vom Modul bereitgestellten API aufgeführt.
 

1. Keine Konfiguration erforderlich – sofort einsatzbereit
   
   Sobald Sie das Modul aktivieren, werden alle Ressourcen mit den entsprechenden Verben, Endpunkten und Feldern verfügbar gemacht. Es erlaubt keine Änderungen an den Konfigurationen (mehr dazu später). Dies stellt sicher, dass die API immer den JSON-API-Spezifikationen folgt und die Bereitstellung schnell und einfach ist.
   
   Alle Bundles erhalten ihre eindeutigen Endpunkte. Wenn eine Entität kein Bundle hat, wird der Entitätstyp wiederholt. Zum Beispiel ist es bei Artikeln /jsonapi/node/article, aber bei Benutzern /jsonapi/user/user. Wir müssen die UUID (Universally Unique Identifier) der Entität angeben, sonst erhalten wir eine „Sammlung“ der Entitäten.
   
   Die Standard-Drupal-Berechtigungen bestimmen die Zugänglichkeit der Ressource. Möglicherweise müssen Sie sich mit Basic Auth oder OAuth authentifizieren, um bestimmte Operationen auszuführen.
   
   Sie können die folgenden Standardanfragen stellen, um CRUD-Operationen an den Ressourcen durchzuführen. Beachten Sie, dass die Konfigurationsentitäten nur die Leseoperation unterstützen, d. h. nur die GET-Anfrage.
    

   Accept: application/vnd.api+json
   Authorization: Basic {base64 encoded username + password}
   Content-Type:application/vnd.api+json
   
   GET /jsonapi/{entity-type}/{bundle-name}?_format=api_json
   GET /jsonapi/{entity-type}/{bundle-name}/{uuid}?_format=api_json 
   POST /jsonapi/{entity-type}/{bundle-name}?_format=api_json
   PATCH /jsonapi/{entity-type}/{bundle-name}/{uuid}?_format=api_json
   DELETE /jsonapi/{entity-type}/{bundle-name}/{uuid}?_format=api_json

   Beispielsweise gibt die folgende Anfrage eine JSON-Antwort der Sammlung aller Artikel zurück (paginiert in Sätzen von 50 Artikeln pro Seite).

   GET /jsonapi/node/article?_format=api_json

   Um einen bestimmten Artikel zu erhalten, müssen Sie seine UUID angeben. Zum Beispiel: 

   GET /jsonapi/node/article/6a1571e0-26c7-423f-8ff5-04b2e4deb6d3?_format=api_json

   

2. Beziehungen einbeziehen
   
   Ein „relationships“-Objekt enthält alle zugehörigen Informationen zur Ressource. Dies können der Autor, Entitätsreferenzen, Bildfelder, Revisionsdetails usw. sein. Normalerweise müssten Sie zusätzliche Anfragen stellen, um weitere Informationen abzurufen. Stattdessen können wir jedoch einen Anfrageparameter „include“ hinzufügen und die erforderlichen Felder dieser zugehörigen Informationen angeben, die abgerufen werden sollen.
   
   Alle zusätzlichen Felder sind im Objekt „included“ verfügbar. Dies stellt sicher, dass wir alle erforderlichen Daten in einer einzigen Anfrage erhalten. Sie können sogar Verschachtelungen in den Beziehungen verwenden, d. h. wenn das Objekt weitere Beziehungen hat, kann dies mit dem Operator „.“ angegeben werden.

   GET /jsonapi/{entity-type}/{bundle-name}?_format=api_json&include={relationships-object}

   Beispielsweise hat das Artikel-Bundle ein Bildfeld (Entitätsreferenz). Wir können seinen Pfad zusammen mit dem Artikel wie folgt abrufen.

   GET /jsonapi/node/article?_format=api_json&include=field_image

   Dieses Mal erhalten wir die JSON-Daten mit einem Objekt „included“ zusammen mit den Daten. Wie Sie vielleicht bemerken, hat es weiterhin UID im Beziehungen-Objekt. Wir können dies abrufen, indem wir include=field_image.uid verwenden.

    "included": [
           {
               "type": "file--file",
               "id": "e7f9cd27-3cd0-43d3-b205-b46e88d09109",
               "attributes": {
                   "fid": 12,
                   "uuid": "e7f9cd27-3cd0-43d3-b205-b46e88d09109",
                   "langcode": "en",
                   "filename": "gen50F1.tmp.jpg",
                   "uri": "public://2018-04/gen50F1.tmp.jpg",
                   "filemime": "image/jpeg",
                   "filesize": 5652,
                   "status": true,
                   "created": 1523243077,
                   "changed": 1523243077,
                   "url": "/drupal-8.4.4/sites/default/files/2018-04/gen50F1.tmp.jpg"
               },
               "relationships": {
                   "uid": {
                       "data": {
                           "type": "user--user",
                           "id": "434ec884-0f9b-4593-8bc4-ef58e542ac0e"
                       },
                       "links": {
                           "self": "/drupal-8.4.4/jsonapi/file/file/e7f9cd27-3cd0-43d3-b205-b46e88d09109/relationships/uid",
                           "related": "/drupal-8.4.4/jsonapi/file/file/e7f9cd27-3cd0-43d3-b205-b46e88d09109/uid"
                       }
                   }
               },
               "links": {
                   "self": "/drupal-8.4.4/jsonapi/file/file/e7f9cd27-3cd0-43d3-b205-b46e88d09109"
               }
           }
       ]

3. Filtern
   
   Filter können auf die Sammlungen angewendet werden, um nur die erforderlichen Ressourcen abzurufen. Sie können mit dem Anfrageparameter „filter“ hinzugefügt werden. Wir müssen das Feld angeben, auf dem der Vergleich durchgeführt werden soll, den Wert, mit dem wir vergleichen müssen, und optional den Operator angeben (Standard ist „=“).

    GET /jsonapi/{entity-type}/{bundle-name}?_format=api_json&filter[label][condition][path]={field}&filter[label][condition][operator]={operator}&filter[label][condition][value]={value}

   Oder

    GET /jsonapi/{entity-type}/{bundle-name}?_format=api_json&filter[field][operator]={operator}&filter[field][value]={value}

   Beispielsweise können wir einen Artikel mit dem Titel suchen, der einige Schlüsselwörter enthält.

    GET /jsonapi/node/article?_format=api_json&filter[title][operator]=CONTAINS&filter[title][value]=search-keyword

   Wir können sogar verschachtelte und gruppierte Filter für fortgeschrittene Anwendungsfälle verwenden. Lesen Sie die offizielle Dokumentation für eine vollständige Referenz.

4. Paginierung
   
   Die Paginierung ist eine gängige Technik, um eine lange Liste von Elementen in Seiten aufzuteilen. Sie kann verwendet werden, um einen unendlichen Scroll oder einfach einen Pager zu implementieren. Dies erfordert zwei Parameter – Limit und Offset. Limit bestimmt die maximale Anzahl (Standard ist 50) und Offset (Standard ist 0) kann verwendet werden, um die ersten „n“ Elemente oder Ressourcen zu überspringen. Das Vorhandensein von „next“- und „prev“-Links zeigt unsere Position im Pager an.

   ​​​​​​​GET /jsonapi/{entity-type}/{bundle-name}?_format=api_json&page[offset]={offset}&page[limit]={limit}

   Beispielsweise können wir einen unendlichen Feed von Artikeln erstellen. Wenn der Benutzer zum Ende scrollt, können wir die folgende Anfrage asynchron verwenden, um beispielsweise 10 weitere Artikel abzurufen.

   ​​​​​​​GET /jsonapi/node/article?_format=api_json&page[offset]=10&page[limit]=10

5. Sparse Fieldsets
   
   Wir können die Felder der Ressource angeben, die zum Ausführen einer GET-Anfrage erforderlich sind, indem wir den Parameter „fields“ verwenden. Dies ist nützlich, wenn wir nur begrenzte Informationen benötigen und Bandbreite sparen möchten.

   GET /jsonapi/{entity-type}/{bundle-name}?_format=api_json&fields[entity-type--bundle]={field(s)}

   Um beispielsweise nur die Titel aller Artikel anzuzeigen, können wir die folgende Anfrage verwenden.

   GET /jsonapi/node/article?_format=api_json&fields[node--article]=title
    
    "data": [
           {
               "type": "node--article",
               "id": "6a1571e0-26c7-423f-8ff5-04b2e4deb6d3",
               "attributes": {
                   "title": "Drupal 8 is awesome"
               },
               "links": {
                   "self": "drupal-8.4.4/jsonapi/node/article/6a1571e0-26c7-423f-8ff5-04b2e4deb6d3"
               }
           },
           {...}
   ]

6. Sortierung
   
   Um eine Sammlung zu sortieren, können wir einen Parameter „sort“ hinzufügen, der das Feld und die Sortierrichtung angibt.

    GET /jsonapi/{entity-type}/{bundle-name}?_format=api_json&sort[label][path]={field}&sort[label][direction]={ASC/DESC}

   Oder

    GET /jsonapi/{entity-type}/{bundle-name}?_format=api_json&sort=±{field}

   Um beispielsweise alle Artikel abzurufen, die nach ihrem Erstellungsdatum und dann nach ihren Titeln sortiert sind, können wir diese Anfrage verwenden:

    GET /jsonapi/node/article?_format=api_json&sort=created,title

   Dies ist keine vollständige Liste. Weitere Details und Beispiele finden Sie in der offiziellen Dokumentation. Mit der richtigen Mischung dieser Funktionen können wir jedoch problemlos alle erforderlichen Funktionen in unserer Headless-Website implementieren.

Anpassen der API

Das Modul bietet keine Möglichkeit, die Ressourcen und die API zu konfigurieren. Wir müssen ein zusätzliches Modul, JSON API Extras, installieren, um die API anzupassen. Mit diesem Modul können wir die Endpunkte und Felder konfigurieren und die Ressourcen aktivieren oder deaktivieren.

1. Navigieren Sie zu Verwalten → Konfiguration → Webdienste → JSON API-Überschreibungen. Hier werden alle verfügbaren Ressourcen aufgelistet. Alle sind standardmäßig aktiviert.

   

2. Klicken Sie auf die Schaltfläche „Überschreiben“ neben der Ressource, die Sie anpassen möchten.
    
3. Sie können den Ressourcentyp, den Pfad oder den Endpunkt ändern, bestimmte Felder deaktivieren und Feldern einen Alias geben. Sie können die Ressourcen deaktivieren, die nicht benötigt werden. Die übrigen Konfigurationen können größtenteils unverändert bleiben.
    

   

4. Klicken Sie auf „Speichern“, wenn Sie fertig sind, um die Konfiguration zu speichern.

Zusammenfassend

Das JSON-API-Modul bietet eine sofort einsatzbereite API für die Produktion. Es bietet Standard-HTTP-Methoden zum Ausführen grundlegender CRUD-Operationen an Entitäten. Es bietet auch einige erweiterte Funktionen, darunter Paginierung, Sortierung und Filterung, um alle erforderlichen Daten in einer einzigen Anfrage abzurufen.

Es fehlen jedoch einige Funktionen wie das Registrieren eines Benutzers, das Anmelden eines Benutzers, das Überprüfen des Anmeldestatus usw. Wir können jedoch den REST-Webdienst von Drupal Core für diesen Zweck verwenden und eine Headless-Website oder eine native mobile Anwendung erstellen, indem wir das Beste aus beiden Welten nutzen. 

Bei OpenSense Labs haben wir an entkoppelten Drupal-Projekten gearbeitet. Senden Sie eine E-Mail an [email protected], um mit uns in Kontakt zu treten.