Anleitung: Verschiedene Ressourcen mit dem REST UI-Modul bereitstellen

Webdienste haben sich in den letzten zwei Jahrzehnten von XML RPC über SOAP zu REST (und in jüngster Zeit zu GraphQL) entwickelt. All dies sind Architekturstile für die Gestaltung von Webdiensten, die bestimmte Prinzipien festlegen. Wir stellen nicht mehr nur HTML-Seiten über HTTP bereit, und Drupal hat dies erkannt, indem es die Unterstützung für REST in den Kern aufgenommen hat.

Das bedeutet, dass wir RESTful APIs mit Drupal als Backend-Lösung erstellen können. Diese APIs können von leistungsstarken Javascript-Frameworks wie Angular, Ember, React oder Vue genutzt werden, um moderne Single-Page-Anwendungen (SPA) oder native mobile Anwendungen für Android/iOS zu erstellen.

Die Kernmodule, die diese Funktionalität bereitstellen, sind jedoch nicht standardmäßig aktiviert. Dazu gehören RESTful Web Services, HTTP Basic Authorization, Serialization und HAL. Sie ermöglichen den Versand von Entitäten, sowohl Inhalten als auch Konfigurationen, in den Datenformaten JSON, XML oder HAL + JSON und bieten außerdem Cookie- und basic_auth-Authentifizierungsmechanismen.

Bevor wir verstehen, wie man diese Ressourcen bereitstellt, konfiguriert und nutzt, wollen wir schnell diese Kernmodule zusammen mit einem sehr nützlichen Zusatzmodul, REST UI, aktivieren. Stellen Sie sicher, dass Sie mindestens RESTful Web Services und Serialization aktivieren, bevor Sie REST UI installieren.

Verwendung von Drush

$ drush en hal basic_auth rest serialization -y
$ drush dl restui && drush en restui -y

Verwendung der Drupal-Konsole

    $ drupal module:install hal basic_auth rest serialization
    $ drupal module:download restui && drupal module:install restui

Verwendung der Benutzeroberfläche

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

Manuelles Bereitstellen von REST-Ressourcen

Um eine REST-Ressource bereitzustellen, müssen wir ihre REST-Ressourcenkonfiguration, d. h. die Konfigurationsdatei rest.resource.*.yml, in die aktive Konfiguration unserer Drupal-Site importieren. Die folgende rest.resource.entity.node.yml deklariert beispielsweise die Verben (oder Methoden), Datenformate und Authentifizierungsmechanismen. Wir können diese Datei importieren, indem wir

admin/config/development/configuration/single/import verwenden oder die Drupal-Konsole nutzen.

drupal config:import:single --file="/path/to/rest.resource.entity.node.yml" .

dependencies:
    module:
      - basic_auth
      - hal
      - node
      - serialization
      - user
  id: entity.node
  plugin_id: 'entity:node'
  granularity: resource
  configuration:
    methods:
      - GET
      - POST
      - DELETE
      - PATCH
    formats:
      - hal_json
      - json
      - xml
    authentication:
      - basic_auth
      - cookie

Wir müssen dies für jede Ressource tun, die verfügbar gemacht werden soll. Um die Dinge zu vereinfachen, kann ein Zusatzmodul REST UI verwendet werden. Dieses Modul listet alle verfügbaren Ressourcen auf und bietet eine Admin-Oberfläche zur Verwaltung dieser Konfigurationsdateien.

Bereitstellen von REST-Ressourcen mit REST UI

1. Navigieren Sie zu Verwalten → Konfiguration → Webdienste → REST. Hier werden alle verfügbaren Ressourcen aufgelistet, die bereitgestellt werden können.
    
2. Um eine dieser Ressourcen zu aktivieren, klicken Sie auf die Schaltfläche "Aktivieren" neben der Ressource, die Sie bereitstellen möchten.

   

3. Wählen Sie die Granularität entweder als Methode oder als Ressource aus. Die Methodengranularität ermöglicht es uns, Datenformate und Authentifizierungsmethoden für jedes der Verben zu definieren, was uns mehr Kontrolle gibt. Aber für den Moment verwenden wir die Ressourcengranularität.
    
4. Wählen Sie als Nächstes die HTTP-Methoden oder -Verben aus, die Sie für diese Ressource aktivieren möchten. POST, GET, PATCH und DELETE werden verwendet, um CRUD-Operationen (Create, Read, Update und Delete) für die Ressource durchzuführen.

   

5. Wählen Sie nun die Authentifizierungsmechanismen aus. Abhängig von den Berechtigungen der Ressource benötigt der RESTful Web Service eine Authentifizierung, um bestimmte Operationen durchzuführen, wie z. B. das Erstellen oder Löschen einer Entität. Sie können auch OAuth 2.0 mit einem Zusatzmodul verwenden.

   Aktivieren und konfigurieren Sie auf ähnliche Weise alle Ressourcen, die Sie über die API versenden möchten.

Testen unserer REST-API

Nachdem wir nun die erforderlichen Ressourcen aktiviert und ihre Konfiguration verwaltet haben, wollen wir die API testen, indem wir grundlegende CRUD-Operationen durchführen. Sie können einen Client wie Restlet Client oder Postman verwenden oder cURL zum Testen verwenden.

Fügen Sie vor dem Fortfahren die folgenden Request-Header hinzu:

1. Erstellen eines Knotens mit POST
   Senden Sie eine POST-Anfrage an {your-drupal-site}/node mit den folgenden Rohdaten im Anfragetext. 

    {
       "_links":{
         "type":{
            "href":"{your-drupal-site}/rest/type/node/article"
         }
       },
       "title":[
         {
           "value":"Test node title"
         }
       ],
       "body":[
         {
           "value":"Test node body",
           "format":"plain_text",
           "summary":"Test node summary"
         }
       ]
     }

   

2. Abrufen eines Knotens mit GET
   
   Senden Sie eine GET-Anfrage an {your-drupal-site}/node/{node_id}. Fügen Sie einen Parameter _format mit dem Wert json, hal_json, html oder xml hinzu. 
   
   Wie Sie vielleicht bemerken, gibt es eine Menge zusätzlicher Informationen zurück, die möglicherweise nicht benötigt werden. Sie können eine Ansicht mit REST Export erstellen und die erforderlichen Felder angeben.

   

3. Aktualisieren eines Knotens mit PATCH
   
   Senden Sie eine PATCH-Anfrage an {your-drupal-site}/node/{node_id} zusammen mit den aktualisierten Knotendaten im angegebenen Format (ähnlich wie bei POST).

   

4. Löschen eines Knotens mit DELETE
   
   Senden Sie eine DELETE-Anfrage an {your-drupal-site}/node/{node_id}.
5. Erstellen einer benutzerdefinierten REST-Ressource
   Wenn Sie schließlich eine benutzerdefinierte REST-Ressource hinzufügen möchten, müssen wir ein benutzerdefiniertes Modul und ein Ressourcen-Plugin erstellen, indem wir die Klasse Drupal\rest\Plugin\ResourceBase erweitern. Sie können den größten Teil des Boilerplate-Codes mit der Drupal-Konsole generieren.

   ​​​​​​​$ drupal generate:plugin:rest:resource

   Implementieren Sie dann die Methoden für jedes der erforderlichen Verben. Aktivieren Sie das benutzerdefinierte Modul und besuchen Sie admin/config/services/rest. Die benutzerdefinierte Ressource kann dann aktiviert werden.

Fazit

Durch die Integration der REST-Dienste von Drupal mit dem REST UI-Modul können wir schnell RESTful APIs bereitstellen, ohne eine einzige Codezeile zu schreiben. Es macht die Erstellung und den Import der YML-Dateien für jede Ressource manuell überflüssig. Wenn Sie planen, mit Drupal Headless zu arbeiten, sollten Sie sich auch das Services-Modul ansehen.