Migration Guide NG 1.1 zu 1.2

Information

Migration Guide 1.1 (v3) zu 1.2 (v4)

Der Hauptteil des Versionswechsel wird als Projekt von unseren Mitarbeitern durchgeführt. Nach dessen Abschluss müssen folgende Änderungen von Ihnen vorgenommen werden.

API Changes

Umbenennung des ID-Parameters

Für folgende Endpunkte muss der Parameter recordId in id umbenannt werden:

  • records/{CHANNEL}/meta/

  • records/{CHANNEL}/full/

  • DELETE records/{CHANNEL}/

Für folgenden Endpunkt muss der Parameter recordIds in ids umbenannt werden:

  • records/{CHANNEL} (DELETE)

Für folgenden Endpunkt muss der Parameter productNumber in id umbenannt werden:

  • campaign/{CHANNEL}/product

Hinzufügen des ID-Typs Add id type to campaign/{CHANNEL}/products API

Der Endpunkt campaign/{CHANNEL}/products kann nun mit Master-Artikelnummern und Artikelnummern verwendet werden. Dazu gibt es den optionalen Parameter idType, der die Werte id (Master-Artikelnummer) oder productNumber (Artikelnummer) annehmen kann.

Neuer HTTP-Statuscode bei Fehlern

Der Endpunkt rest/v4/detail/{channel}/{recordId} gibt bei nun den HTTP-Status 404 (Not Found) anstelle von 500 (Internal Server Error) zurück, wenn die Details für eine unbekannte Artikelnummer angefragt werden. Dies gilt es bei der Fehlerbehandlung zu beachten, wenn der API-Proxy nicht genutzt wird.

Rückgabe der Feldrollen beim Endpunkt /rest/v3/records/{channel} (GET)

Der Endpunkt /rest/v3/records/{channel} (GET) gibt nun zusätzlich zu den Records ein Mapping von Feldrollen zu Feldnamen zurück. Das geänderte Format muss bei der Verarbeitung beachtet werden. Weiterhin wird die Anfrage nicht länger mit dem Fehler 400 (Bad Request) abgebrochen, wenn eine Artikelnummer enthalten ist. Stattdessen werden alle gefundenen Records zurückgegeben oder eine leere Liste, wenn keine Records gefunden wurden.

Rückgabe der Feldrollen beim Endpunkt /rest/v3/records/{channel}/full (GET)

Der Endpunkt /rest/v3/records/{channel}/full (GET) gibt nun zusätzlich zu den Records ein Mapping von Feldrollen zu Feldnamen zurück. Die zusätzliche Rückgabe der ID des Records in der Antwort ist entfallen und kann nicht länger verwendet werden. Das geänderte Format muss bei der Verarbeitung beachtet werden. Weiterhin wird die Anfrage nicht länger mit dem Fehler 400 (Bad Request) abgebrochen, wenn eine Artikelnummer enthalten ist. Stattdessen werden alle gefundenen Records zurückgegeben oder eine leere Liste, wenn keine Records gefunden wurden.

Suggestion-Attribute nutzen Feldnamen anstelle von Konstanten

Die Attribute von Suggestions wurden zuvor über Konstanten wie productNumber, masterId und deeplink referenziert. Die Konstanten wurden entfernt und durch die Feldnamen ersetzt.

Das Attribut articleNr wurde entfernt. Das neu enthaltene Flag articleNumberSearchAllowed kann nun genutzt werden, um sicherzustellen, dass eine Suche nach dem Wert aus dem Feld mit der Feldrolle productNumber eine Artikelnummernsuche nach dem gewünschten Produkt ausführt.

Die Änderungen gelten für die GET- und POST-Endpunkte.

Rückgabe der Feldrollen bei Suggest-Endpunkten

Die Suggest-Endpunkte geben nun zusätzlich zu den Suggestions ein Mapping von Feldrollen zu Feldnamen zurück. Außerdem ist das zusätzliche Attribut articleNumberSearchAllowed enthalten.

Die Änderungen gelten für die GET- und POST-Endpunkte.

Änderung des HTTP-Statuscodes bei Anfrage von deaktivierten Modulen

Zuvor lieferte eine Anfrage an ein deaktiviertes Modul den HTTP-Statuscode 500 (Internal Server Error) zurück. Der neue Statuscode bei entsprechenden Anfragen ist 403 (Forbidden).

Die Anpassung gilt für folgende Endpunkte:

  • GET /rest/v4/campaign/{channel}/page

  • GET /rest/v4/campaign/{channel}/shoppingcart

  • GET /rest/v4/campaign/{channel}/product

  • POST /rest/v4/management/deploy

  • POST /rest/v4/management/flushCache

  • POST /rest/v4/import/recommendation

  • POST /rest/v4/import/suggest

  • POST /rest/v4/navigation

  • GET /rest/v4/navigation/{channel}

  • GET /rest/v4/navigation/category/{channel}

  • GET /rest/v4/suggest/{channel}

  • POST /rest/v4/suggest

  • GET /rest/v4/records/{channel}/recommendation

Für einige Anfragen hat sich ebenfalls die Fehlerbeschreibung geändert.

Encoding der Werte von Kategoriepfaden als Array

Zuvor wurden Werte von Kategoriepfaden als String bei einer Suchanfrage mitgegeben. Dadurch mussten einzelne Werte unter Verwendung von / aneinandergereiht und ein auftretendes / im Namen eines Wertes wie im Pfad "Bekleidung" - "3/4 Hosen" musste als "Bekleidung/3%2F4 Hosen" dargestellt werden. Nun werden solche Pfade als Arrays übergeben und das ein entsprechendes Encoding der Werte entfällt.

POST-Endpunkt

Vorher:

"filters": [
  {
     "name": "Category",
     "values": [
      {
         "value": "Outdoor clothing/Outdoor jackets",
         "type": "or",
         "exclude": false
      }
    ],
     "substring": false
  }
],
...

Nachher:

"filters": [
  {
     "name": "Category",
     "values": [
      {
         "value": [
                     "Outdoor clothing",
                     "Outdoor jackets"
                  ],
         "type": "or",
         "exclude": false
      }
    ],
     "substring": false
  }
],
...

Antwort

Antworten auf Suchanfragen enthalten die Werte von Kategoriepfaden nun auch in Form eines Arrays wie oben anhand des Beispiels gezeigt.

Änderungen an REST-API für Gruppen-Management

Die REST-API für das Gruppen-Management hat Usability-Verbesserungen erhalten.

Die folgenden Endpunkte liefern keine id mehr innerhalb der group-Segmente:

  • GET /rest/v4/groups

  • POST /rest/v4/groups

  • PUT /rest/v4/groups

  • DELETE /rest/v4/groups

  • DELETE /rest/v4/groups/{groupName}

Änderungen an REST-API für Benutzer-Management

Die REST-API für das Benutzer-Management hat Usability-Verbesserungen erhalten.

Der Endpunkt /rest/v3/users (PUT) wurde in zwei Endpunkte aufgeteilt:

  • /rest/v4/users (PUT) kann genutzt werden, um Berechtigungen (roles, channels, groups und allowAllCurrentAndFutureChannels) und UI-Einstellungen (hideInactiveModules, hideErrorNotifications, enableAdvanceMode und locale) zu setzen. Die password-Einstellung wurde entfernt und kann nicht mehr verwendet werden. Die Berechtigungen und UI-Einstellungen müssen bei Verwendung der API in entsprechende Objekte gekapselt werden (permissions und uiSettings).

  • /rest/v4/users/{userName}/password (PUT) kann genutzt werden, um das Passwort eines Benutzers zu ändern. Hierzu muss lediglich das Passwort übergeben werden.

Die Antwort-Struktur der Benuter-Management-Endpunkte, die Benutzer-Informationen zurückliefern, wurde geändert. So wurde das Attribut id entfernt und die roles, channels, groups und allowAllCurrentAndFutureChannels sind in einem permissions-Objekt zusammengefasst. Darüber hinaus wurden die Attribute hideInactiveModules, hideErrorNotifications, enableAdvanceMode und locale in einem uiSettings-Objekt zusammengefasst.

Auch der Endpunkt /rest/v3/users (POST) weist ein verändertes Eingabeformat auf:

  • roles, channels, groups und allowAllCurrentAndFutureChannels müssen nun in einem permissions-Objekt sowie hideInactiveModules, hideErrorNotifications, enableAdvanceMode und locale in einem uiSettings-Objekt bereitgestellt werden.

Verschieben des associatedFieldName von Facetten-Elementen zur Facette

Der associatedFieldName wurde zuvor in Teil der Facetten-Elemente unter elements zurückgeliefert und wurde nun eine Ebene höher geschoben, um redundante Daten zu vermeiden. Er wird nun direkt als Teil der Facette zurückgeliefert. Die Änderung betrifft folgende Endpunkte:

  • POST /rest/v4/navigation

  • GET /rest/v4/navigation/{channel}

  • GET /rest/v4/navigation/category/{channel}

  • GET /rest/v4/search/{channel}

  • POST /rest/v4/search

Hinzufügen eines Endpunktes für das Tracking von Klicks auf Landing Pages

Bisher wurden Klicks auf Landing Pages immer über den üblichen Endpunkt für Klick-Events übergeben, wobei ein Suchbegriff zwingend erforderlich ist. Da bei einem Klick auf einer Landing Page allerdings noch kein Suchbegriff eingegeben wurde, handelte es sich hierbei um einen Platzhalter-Wert. Es gibt nun den Endpunkt /rest/v4/track/{channel}/landingPageClick, der ohne einen Suchbegriff zu diesem Zweck verwendet werden kann. Der Endpunkt erwartet Informationen über das geklickte Produkt, die Session, die Kampagne und die Landing Page. Weiterhin gibt es einige optionale Parameter. Für weitere Informationen sei auf die Swagger-UI verwiesen.

Swagger Link

.../fact-finder


**Beispiel: https://ng-demo.fact-finder.de/fact-finder/swagger-ui.html

Ausgehende Klicks einer Landing Page werden wie Klicks von Detailseiten geschrieben, allerdings ohne Informationen über page, pageSize, score und position. Als Suchbegriff wird fest fromLandingPage:{PAGE_ID} verwendet, um Analysen über Analytics zu ermöglichen.

Die ASO wird entsprechende Klicks ignorieren, da diese keinem echten Suchbegriff zugeordnet werden können.

Parameter page des Klick-Trackings optional

Der Parameter page des Endpunktes /rest/v4/track/{channel}/click ist nun optional, da ein Klick-Event auch ohne diese Information einen Nutzen bietet.