• Holm Gehre
• 17.05.2017
• DE

REST Web Services und JSON-Response mit dem Delivery Server

»REST« und »JSON« sind in aller Munde und auch die Version 16 des Delivery Servers bietet einige dieser Funktionen, wie Markus Heckmann (OpenText) in seinem Vortrag: "REST API's im Delivery Server" auf der 41. Anwenderkonferenz in Hamburg zeigte. Doch was geht nun leichter im Vergleich zu den Vorgängern?
 

REST API's

Mit der Version 16 des OTWSM Delivery Servers stehen "REST API's" zur Abfrage von: Tempo Social; Reporting; SOLR/InfoFusion und Delivery Server Projektinhalten zur Verfügung.

Wo "versteckt" sich die neue REST API? Der folgende Screenshot zeigt den Weg: Server Manager > System > REST API anzeigen.

---

Anmerkung: Ich habe nur die REST API's für SOLR, die von mir verwendete Version 4.8.1 wurde vollumfänglich unterstützt, und OTWSM DS Projektinhalte angesprochen. Tempo Social und Reporting ist auf meiner Testumgebung nicht installiert und lizensiert.

---

SOLR - REST API

Die SOLR - REST API empfinde finde ich als super Erweiterung des OpenText™ Web Site Management Delivery Server, da die SOLR-Abfragen ohne zusätzliches Rendern (XML/XSL - Transformation) auskommen und Ergebnisse ohne Umschweife verwendet werden können.

Nachfolgend meine einfachen Tests mit dem "Xample - Projekt" und dem Aufruf via Swagger UI - direkt über den Delivery Server.

Suche nach "Management" im Xample-Projekt zeigt folgende Ergebnisse:

Der direkte Delivery Server - Aufruf liefert das Suchergebnis als JSON-Response in den Standardeinstellungen. Möchte man ein anderes Ergebnis (z.B XML) ist der Parameter "nativquery" anzupassen.

 

Delivery Server Projekt - REST API

Im Gegensatz zur SOLR - Anbindung hat mich die REST API für Projektinhalte nicht überzeugen können. Dies liegt in der REST Service - Antwort begründet, da her nur die ungerenderte XML-Antwort mit den zu ersetzenden Platzhaltern (z.B. PSX-Module, RDE-URL - Angaben) ausgeliefert wird. Diese Antwort entspricht also haargenau der Antwort, die ich vom Delivery Server erhalte, wenn ich die URL: "/cps/rde/[projektname]/[path/contentname]" aufrufe. Für Projekte, in denen keine Namenseindeutigkeit auf Gruppenebene gewählt wurde, muss beim Aufruf der Inhalte über die API nichtsdestotrotz der "volle" Pfad zum Inhalt übergeben werden.

Nachfolgend mein Beispielaufruf:

 

Eigene Services implementieren

Inhalte (z.B. Suchergebnisse, Daten aus Datenbanken) als Service über den Delivery Server zur Verfügung zu stellen, war aber auch in den Vorgängerversionen nicht unmöglich.
Das Model-View-Controller - Prinzip (MVC) ist der hierfür am häufigsten gewählte Ansatz. Einen guten Einstieg in die Modulentwicklung mit dem Delivery Server bietet aus meiner Sicht der Blogeintrag: "Module Development with Delivery Server" von Bernfried Howe.

Andere mir bekannte Lösungen bilden einen eigenen REST-Service über eine bestimmte Projektstruktur (u.a. Namenseindeutigkeit auf Gruppenebene) und dem Einsatz der Open API ab. Nachfolgend eine "praktikable" Projektstruktur, die dem Service-Ansatz folgt und für jede Version (hier: v1) eine eigene Inhaltsgruppe nutzt.

Wer sich für die eigene Implementierung von Services mit dem Delivery Server interessiert und neben diesem Artikel noch die eine oder andere Anregung sucht, dem möchte ich an dieser Stelle auch das DSaaS - Delivery Server as a Service - REST API for DynaMents von Tim Davis ans Herz legen.

JSON - Response mit dem Delivery Server

Ein weiteres Feature in Release 16 des OpenText™ WSM Delivery Servers ist das neue Standard-Attribut "convert-type", mit dem XML-Daten auf einfache Weise in JSON (JavaScript Object Notation) überführt werden können. 

In den führeren Versionen ist hierfür der Einsatz weiterer Dynaments und/oder XSL Transformation (XSLT) notwendig.

Mit den folgenden einfachen Beispielen möchte ich eine kurze Einführung in die Thematik: JSON-Response mit dem Delivery Server geben.

1. statische JSON-Dateien vom DeliveryServer ausliefern

Statische JSON-Dateien auszuliefern ist die einfachste Möglichkeit um einen JSON-Response zu erzeugen. Hierfür muss nur der korrekte MIME-Type: application/json gesetzt und mitgesendet werden, da anderenfalls der Typ: text/html verwendet wird.

 JSON 
<rde-dm:attribute mode="write" attribute="request:rdeResponseMimetype" op="set" value="application/json"/>
{"data": {
  "var1": "1",
  "var2": "2",
  "var3": "3"
}}

 

2. XML-Daten in JSON wandeln mit convert-type

Zunächst wird eine XML-Datei benötigt. Der Einfacheit halber habe ich diese wie folgt aufgebaut und "jsondaten.xml" benannt.

 XML 
<?xml version="1.0" encoding="UTF-8"?>
<data>
  <var1>1</var1>
  <var2>2</var2>
  <var3>3</var3>
</data>

Als nächstes die Datei "data.json", welche die obere XML-Datei einliest und in JSON wandelt.

 Dynament 
<rde-dm:attribute mode="write" attribute="request:rdeResponseMimetype" op="set" value="application/json"/>
<rde-dm:include content="jsondaten.xml" convert-type="json" />

Die Antwort "überrascht"! Das Root-Tag "data" fehlt und es werden einige Delivery Server-Attribute sowie die 3 Variablen ausgegeben.

Um den gewünschten Output zu erhalten, ist der Inhalt der XML-Datei "jsondaten.xml" um ein weiteres Tag zu ergänzen (hier: dynament).

 XML 
<?xml version="1.0" encoding="UTF-8"?>
<dynament>
  <data>
    <var1>1</var1>
    <var2>2</var2>
    <var3>3</var3>
  </data>
</dynament>

Sieht schon besser aus, aber die Delivery Server - Attribute möchte ich nicht in der Antwort haben, da diese Rückschlüsse auf die eingesetzte Software (hier OpenText™ WSM Delivery Server) zulassen.

Da mir kein Attribut (ausser tag="notag" und mode="noroot"; beide funktionieren nicht) für das Include-Dynament bekannt ist, welches diesen Output unterdrückt, habe ich die "data.json" wie folgt umgebaut und in "xml2json.xml" umbenannt.

 Dynament 
<?xml version="1.0" encoding="UTF-8"?>
<dynament>
  <rde-dm:attribute attribute="request:rdeResponseMimetype" mode="write" op="set" value="application/json" />
  <rde-dm:include content="jsondaten.xml" mode="text" process-mode="execute" rde-id="!xmldata" />
  <rde-dm:attribute attribute="request:data" mode="write" op="set">
    <rde-dm:value><![CDATA[]]></rde-dm:value>
  </rde-dm:attribute>
  <rde-dm:attribute attribute="request:data" mode="write" op="concat" value="[#rde-id:xmldata:dynament#]" />
  <rde-dm:attribute attribute="request:data" mode="write" op="concat">
    <rde-dm:value><![CDATA[]]></rde-dm:value>
  </rde-dm:attribute>
  <rde-dm:attribute attribute="request:data" convert-type="json" mode="read" op="xml" />
</dynament>

---

Anmerkung: Die CDATA-Blöcke sind nicht zwingend notwendig und können auch weggelassen werden.

---

Das Ergebnis entspricht nun meinen Erwartungen:

 

3. XML-Daten in JSON wandeln ohne convert-type 

Wie funktioniert das Wandeln ohne das Standard-Attribut? Der folgende Beispielcode durchläuft das XML mit einer "for-each"-Schleife und gibt die Inhalte entsprechend aus. Ein vergleichbares Ergebnis ließe sich auch mit einer XSL Transformation erzeugen.

 Dynament 
<?xml version="1.0" encoding="UTF-8"?>
<dynament>
 <rde-dm:attribute mode="write" attribute="request:rdeResponseMimetype" op="set" value="application/json"/>
 <rde-dm:include content="jsondaten.xml" process-mode="execute" rde-id="!xmldata" />
 <![CDATA[ { ]]>
 <rde-dm:attribute alias="item" attribute="rde-id:xmldata:dynament" mode="for-each" type="node">
 <![CDATA[ "data": ]]>
   <![CDATA[ { ]]>
  <![CDATA[ "var1":"]]><rde-dm:attribute attribute="context:item.var1" mode="read" tag="notag" /><![CDATA[",]]>
  <![CDATA[ "var2":"]]><rde-dm:attribute attribute="context:item.var2" mode="read" tag="notag" /><![CDATA[",]]>
  <![CDATA[ "var3":"]]><rde-dm:attribute attribute="context:item.var3" mode="read" tag="notag" /><![CDATA["]]>
  <![CDATA[ } ]]>
 </rde-dm:attribute>
 <![CDATA[ } ]]>
</dynament>

Das Ergebnis ohne "convert-type":

---

Fazit

Die neuen Funktionen bieten einige Erleichterungen bei der Umsetzung von Projektanforderungen und der Bereitstellung von Daten. Mit dem neuen REST-Weblet und den daraus resultierenden URL-Pfad Änderungen ergeben sich aber auch neue Herausforderungen an Rewrite-Regeln und Zugriffsberechtigungen.
Die Erweiterungen in Version 16 des OTWSM Delivery Servers sind aus meiner Sicht ein guter erster Schritt auf dem Weg zu "Content as a Service" (CaaS) und der Verarbeitung bzw. Bereitstellung von JSON-Daten.
Ich würde mir für den Abruf von Delivery Server Projektinhalten über die REST API wünschen, dass diese entweder über das integrierte Stylesheet ("rdesrdef.xsl") oder über ein, dem Service zu übergebendes Stylesheet, gerendert werden.

---

Über den Autor: