Migration Guide von JSON/XML zu REST

Die nachfolgenden Informationen gelten unabhängig vom gewählten Rückgabeformat (JSON oder XML). Der Einfachheit halber ist exemplarisch format=json als Parameter angegeben. Dieser Parameter entfällt in der REST-API.

Informationen zu neuen, nicht verpflichtenden Parametern der REST-Endpunkte sowie die zugehörigen Rückgabewerte entnehmen Sie bitte der API-Dokumentation zu Ihrer FACT-Finder-Installation (https://<Ihre Basis-URL>/fact-finder/swagger-ui.html).

Allgemeines

Authentifizierung

Ab dem 01.04.2022 wird OAuth2 nicht mehr von FACT-Finder unterstützt.

Als Optionen zur Authentifizierung steht Basic Authentication zur Verfügung:

Basic Authentication

Um sich mit Basic Authentication zu authentifizieren, muss der Authorization-Header folgendes enhalten: das Wort Basic, gefolgt von einem Leerzeichen und der Base64-encodierten username:passwort-Zeichenkette. Ein Header mit den Anmeldedaten factfinder:pw würde so aussehen: Authorization: Basic ZmFjdGZpbmRlcjpwdw=. ZmFjdGZpbmRlcjpwdw== ist hierbei die Base64-Repräsentation von factfinder:pw.

Fehlermeldungen

Fehlermeldungen (4xx und 5xx) werden als einzelne Fehlermeldung mit folgender Struktur zurückgegeben:

Response

{

"error": "Bad Request",

"errorDescription": "Channel 'abcde' does not exist.",

"stacktrace":

[

"stack trace",

"as array"

]

}

ProductCampaign

getProductCampaigns

Den entsprechenden REST-Endpunkt zu /ProductCampaign.ff?do=getProductCampaigns&format=json&… finden Sie unter /rest/v4/campaign/{channel}/product (GET).

Der Parameter idOnly wurde zu idsOnly umbenannt.

Der verpflichtende Parameter articleNumber wurde zu id umbenannt.

getShoppingCartCampaigns

Den entsprechenden REST-Endpunkt zu /ProductCampaign.ff?do=getShoppingCartCampaigns&format=json&… finden Sie unter /rest/v4/campaign/{channel}/shoppingcart (GET).

Der Parameter idOnly wurde zu idsOnly umbenannt.

Der verpflichtende Parameter articleNumberList wurde zu productNumber umbenannt.

getPageCampaigns

Den entsprechenden REST-Endpunkt zu /ProductCampaign.ff?do=getPageCampaigns&format=json&… finden Sie unter /rest/v4/campaign/{channel}/page (GET).

Der Parameter idOnly wurde zu idsOnly umbenannt.

Delete

Den entsprechenden REST-Endpunkt zu /Delete.ff finden Sie unter /rest/v4/records/{channel} (DELETE).

Der Parameter save ist entfallen, da er nicht mehr benötigt wird.

Insert

Den entsprechenden REST-Endpunkt zu /Insert.ff finden Sie unter /rest/v4/records/{channel} (POST).

Die Parameter save und fieldname sind entfallen, da sie nicht mehr benötigt werden.

Der verpflichtende Parameter records (application/json, body) wurde hinzugefügt. Er nimmt JSON-formatierte Einträge im Format [FlatRecord { worldmatch record }] entgegen.

Update

Den entsprechenden REST-Endpunkt zu /Update.ff finden Sie unter /rest/v4/records/{channel} (PUT).

Die Parameter save und fieldname sind entfallen, da sie nicht mehr benötigt werden.

Der verpflichtende Parameter records (application/json, body) wurde hinzugefügt. Er nimmt JSON-formatierte Einträge im Format [FlatRecord { worldmatch record }] entgegen.

Import

Suche

Den entsprechenden REST-Endpunkt zu /Import.ff?format=json&channel={channel(s)} finden Sie unter /rest/v4/import/search (POST).

Suggest

Den entsprechenden REST-Endpunkt zu /Import.ff?format=json&type=suggest&channel={channel(s)} finden Sie unter /rest/v4/import/suggest (POST).

Der Parameter type ist entfallen. Stattdessen erhält der Suggest-Import einen eigenen Endpunkt.

Compare

Den entsprechenden REST-Endpunkt zu /Compare.ff&format=json&… finden Sie unter /rest/v4/records/{channel}/compare (GET).

Der Parameter recordIds wurde zu id umbenannt.

Recommender

importData

Den entsprechenden REST-Endpunkt zu /Recommender.ff?do=importData&format=json&… finden Sie unter /rest/v4/import/recommendation (POST).

Der Parameter download ist entfallen.

getRecommendation

Den entsprechenden REST-Endpunkt zu /Recommender.ff?do=getRecommendation&format=json&… finden Sie unter /rest/v4/records/{channel}/recommendation (GET).

Der verpflichtende Parameter productId wurde zu id umbenannt.

Der Parameter maxRecommendations wurde zu maxResults umbenannt.

Search

Den entsprechenden REST-Endpunkt zu /Search.ff?format=json&… finden Sie unter /rest/v4/search (POST) bzw. /rest/v4/search/{channel} (GET).

Die folgenden Parameter sind entfallen:

detailCustomParameters (params)
followSearch (params)
articleNumber (params)
seoPath (params)
generateAdvisorTree (searchControlParams)
useKeywords (searchControlParams)
queryOrigin (trackingInformation)
site (trackingInformation)

Der Parameter filters (params) wurde zu filter umbenannt.

Der Parameter noArticleNumberSearch (params) wurde zu articleNumberSearch. Er legt fest, ob die Abfrage als Artikelnummer interpretiert werden soll. Bei DETECT wird automatisiert ermittelt, ob es sich bei der Abfrage um eine Artikelnummer handelt, ALWAYS interpretiert den Suchbegriff stets als Artikelnummer, NEVER nie. Der Standardwert ist DETECT.

Der Parameter resultsPerPage (params) wurde zu hitsPerPage umbenannt.

Der Parameter disableCache (searchControlParams) wurde zu useCache. Dadurch ergibt sich eine Umkehrung der Werte! Wenn true, wird das Ergebnis aus dem Cache zurückgegeben, falls ein passender Eintrag existiert. Der Standardwert ist true.

Der Parameter sessionID (trackingInformation) wurde zu sid umbenannt.

Der Parameter sortsList (params) wurde zu sort umbenannt.

Suggest

Den entsprechenden REST-Endpunkt zu /Suggest.ff?format=json&… finden Sie unter /rest/v4/suggest (POST) bzw. /rest/v4/suggest/{channel} (GET).

Die folgenden Parameter sind entfallen:

detailCustomParameters (params)
followSearch (params)
articleNumber (params)
seoPath (params)
sortsList (params)
disableCache (searchControlParams)
generateAdvisorTree (searchControlParams)
idsOnly (searchControlParams)
useAsn (searchControlParams)
useAso (searchControlParams)
useCampaigns (searchControlParams)
useFoundWords (searchControlParams)
useKeywords (searchControlParams)
usePersonalization (searchControlParams)
useSemanticEnhancer (searchControlParams)

Der Parameter filters (params) wurde zu filter umbenannt.

Der Parameter noArticleNumberSearch (params) wurde zu articleNumberSearch. Er legt fest, ob die Abfrage als Artikelnummer interpretiert werden soll. Bei DETECT wird automatisiert ermittelt, ob es sich bei der Abfrage um eine Artikelnummer handelt, ALWAYS interpretiert den Suchbegriff stets als Artikelnummer, NEVER nie. Der Standardwert ist DETECT.

Der Parameter resultsPerPage (params) wurde zu hitsPerPage umbenannt.

SimilarRecords

Den entsprechenden REST-Endpunkt zu /SimilarRecords.ff?format=json&… finden Sie unter /rest/v4/records/{channel}/similar (GET).

Der Parameter recordId (params) wurde zu id umbenannt.

Der verpflichtende Parameter idType (string, query) wurde hinzugefügt. Er spezifiziert, welchen Typ die ID besitzt.

Es existiert kein entsprechender REST-Endpunkt zu /TagCloud.ff?do=getTagCloud&format=json&…, da die Funktion entfallen ist.

Tracking

Die entsprechenden REST-Endpunkte zu /Tracking.ff?… finden Sie unter /rest/v4/track/{channel}/… (POST).

Es existieren derzeit die folgenden Tracking-Endpunkte:

/rest/v4/track/{channel}/cart

Tracking von Cart-Events

/rest/v4/track/{channel}/checkout

Tracking von Checkout-Events

/rest/v4/track/{channel}/click

Tracking von Click-Events

/rest/v4/track/{channel}/feedback

Tracking von Feedback-Events

/rest/v4/track/{channel}/landingPageClick

Tracking von Click-Events für Produkte, die durch eine Kampagne auf einer Landing-Page bereitgestellt wurden.

/rest/v4/track/{channel}/log

Tracking von Log-Events

/rest/v4/track/{channel}/login

Tracking von Log-In-Events

/rest/v4/track/{channel}/predbasketClick

Tracking von Predictive-Basket-Klickevents

/rest/v4/track/{channel}/recommendationClick

Tracking von Recommendation-Klickevents

Nähere Informationen zu den einzelnen Tracking-Endpunkten entnehmen Sie bitte der API-Dokumentation zu Ihrer FACT-Finder-Installation (https://<Ihre Basis-URL>/fact-finder/swagger-ui.html).