Storefront API URL-Resolution

Die URL-Resolution API übersetzt zwischen Adressen und Shop-Ressourcen, und zwar in beide Richtungen. urls/identify beantwortet die Frage, welche Seite unter einer aufgerufenen Adresse angezeigt werden soll, und ist damit der Einstiegspunkt für das Routing einer eigenen Storefront. urls/product und urls/category gehen den umgekehrten Weg und liefern zu einer bekannten ID die passende Adresse, beispielsweise um Links in Listen und Navigationen zu erzeugen. Ein typischer Ablauf ist: Die Storefront übergibt die aufgerufene Adresse an urls/identify, erhält Seitentyp und ID zurück und lädt die Inhalte anschließend über die Katalog API. Welcher Subshop antwortet, ergibt sich aus der Domain, gegen die die Aufrufe gehen. Mehr dazu unter Storefront API Basics. Da SEO-URLs je Subshop gepflegt werden, liefert dieselbe Adresse in verschiedenen Subshops unterschiedliche Ergebnisse.

Die Endpunkte dieser Seite benötigen keinen x-session-Header. Ein mitgesendeter Header stört nicht.

Unterstützte Methoden

Angabe aller unterstützten Methoden.

Befehl	Endpunkte	GET	PUT	POST	DELETE
Adresse einem Seitentyp zuordnen	`urls/identify`
URL eines Produkts ermitteln	`urls/product`
URL einer Kategorie ermitteln	`urls/category`

Alle anderen HTTP-Methoden beantworten die Endpunkte mit 404 Not Found.

Methoden für die URL-Resolution

GET urls/identify

Folgender Aufruf ordnet eine eingehende Adresse einer Shop-Ressource zu. Die Antwort sagt, welcher Seitentyp zu rendern ist, welche Ressource dazu geladen werden muss und ob stattdessen weitergeleitet werden soll. Der Endpunkt ist für Storefronts gedacht, die das Routing selbst übernehmen. Die Storefront gibt die vom Besucher aufgerufene Adresse hinein und entscheidet anhand der Antwort, ob sie eine Produktseite, eine Kategorieseite, eine Weiterleitung oder eine 404-Seite ausliefert. Beispiel-Aufruf

GET https://<ihr-shop>.de/api/v1/urls/identify?url=/herren/schuhe/sneaker

Parameterübersicht

Parameter	Typ	Beschreibung
`url`	string	Pflichtfeld Der aufgerufene Pfad, URL-kodiert. Die Startseite wird als `/` übergeben. Weitere Query-Parameter werden mit `invalidParameters` abgelehnt.

Der Abgleich erfolgt zeichengenau gegen die gespeicherten SEO-URLs. Ein abweichender abschließender Schrägstrich oder eine abweichende Groß- und Kleinschreibung führen deshalb zu 404 Not Found. Ein Query-String, der im Wert von url mitgegeben wird, führt ebenfalls zu 404 Not Found. Zusätzliche Query-Parameter am Endpunkt selbst werden dagegen mit 400 invalidParameters abgelehnt. Übergeben Sie ausschließlich den Pfad, mit führendem Schrägstrich und ohne Query-String.

Antwortfelder

Feld	Typ	Beschreibung
`found`	bool	`true`, wenn die Adresse einer Ressource zugeordnet werden konnte. `false` bedeutet, dass die Adresse dem Shop bekannt ist, die Ressource aber nicht mehr existiert. In diesem Fall steht in `redirect` das Weiterleitungsziel.
`type`	string	Seitentyp, siehe folgende Tabelle.
`id`	string	Optional Kennung der Ressource, mit der anschließend die Seitendaten geladen werden. Bei `Startpage` entfällt das Feld.
`redirect`	string	Optional Pfad, auf den weitergeleitet werden soll. Das Feld ist nur vorhanden, wenn eine Weiterleitung erfolgen soll.

Seitentypen

Typ	Inhalt von `id`	Beschreibung
`Product`	Produkt-ID	Produktseite. Die Daten werden über `catalog/product/load` geladen.
`Category`	Kategorie-ID	Kategorieseite. Die Daten werden über `catalog/category/load` geladen.
`View`	Template-Pfad	Template-Seite mit eigener SEO-URL, beispielsweise `content/gtc.htm`. Das ist keine Katalog-ID, die Seite wird nicht über die Katalog API geladen.
`Startpage`	entfällt	Startseite des Shops. Wird nur bei `url=/` geliefert.

Der Wert von type ist die Kennung des zuständigen View-Controllers. Kommen im Shop weitere Seitentypen mit eigenen SEO-URLs zum Einsatz, können auch deren Kennungen erscheinen. Fangen Sie unbekannte Werte deshalb ab und geben Sie in diesem Fall Ihre eigene 404-Seite aus.

Antworten im Überblick

Situation	HTTP	`found`	`redirect`	Empfohlene Reaktion
Adresse ist die aktuelle Adresse einer vorhandenen Ressource	200	`true`	entfällt	Seite regulär aufbauen
Adresse ist eine Alt-Adresse derselben Ressource	200	`true`	aktuelle Adresse	301 auf `redirect`
Ressource gelöscht, im Shop ist ein Weiterleitungsziel hinterlegt	200	`false`	Weiterleitungsziel	301 auf `redirect`
Ressource gelöscht oder deaktiviert, kein Weiterleitungsziel hinterlegt	200	`true`	entfällt	Laden schlägt fehl, eigene 404-Seite ausgeben
Adresse ist dem Shop unbekannt	404	entfällt	entfällt	eigene 404-Seite ausgeben

Beispiel-Response: vorhandene Ressource

{
  "found": true,
  "type": "Product",
  "id": "146-78608"
}

Beispiel-Response: Startseite

{
  "found": true,
  "type": "Startpage"
}

Beispiel-Response: Template-Seite

{
  "found": true,
  "id": "content/gtc.htm",
  "type": "View"
}

Beispiel-Response: Alt-Adresse derselben Ressource

{
  "found": true,
  "type": "Product",
  "id": "146-78608",
  "redirect": "/herren/schuhe/sneaker-air-146-78608"
}

Der Shop führt zu einer Ressource mehrere SEO-URLs. Ändert sich der generierte Pfad, beispielsweise durch eine Umbenennung, einen Kategoriewechsel oder eine manuell gesetzte URL, wird die neue Adresse zur aktuellen Adresse. Die bisherige bleibt als Alt-Adresse bestehen und wird nicht gelöscht, damit Lesezeichen und Suchmaschinen-Treffer weiter funktionieren. Damit beide Adressen nicht dauerhaft denselben Inhalt ausliefern, sollte die Storefront hier auf die aktuelle Adresse weiterleiten. Die Ressource selbst ist unverändert vorhanden, type und id beschreiben sie korrekt.

Beispiel-Response: gelöschte Ressource mit Weiterleitungsziel

{
  "found": false,
  "type": "Product",
  "id": "146-78608",
  "redirect": "/herren/schuhe"
}

In diesem Fall beschreiben type und id die nicht mehr vorhandene Ressource. Sie dürfen nicht zum Laden von Seitendaten verwendet werden, auswertbar ist hier nur redirect.

Beispiel-Response: unbekannte Adresse

HTTP/1.1 404 Not Found

Der Response-Body ist leer.

Auswertung in der Storefront

Werten Sie die Antwort in dieser Reihenfolge aus:

HTTP-Status 404: Die Adresse ist dem Shop unbekannt. Geben Sie Ihre eigene 404-Seite aus.
Feld redirect vorhanden: Leiten Sie auf diesen Wert weiter, empfohlen mit Status 301. Das gilt sowohl für Alt-Adressen als auch für gelöschte Ressourcen. Prüfen Sie redirect deshalb vor found.
Kein redirect, found ist true: Bauen Sie die Seite regulär auf. type bestimmt den Seitentyp, id ist die Ressource für den anschließenden Aufruf von catalog/product/load beziehungsweise catalog/category/load.
Der Ladeaufruf kommt leer zurück: Die Ressource ist deaktiviert oder gelöscht, ohne dass ein Weiterleitungsziel hinterlegt ist. Geben Sie Ihre eigene 404-Seite aus.

Ruft ein Besucher eine Alt-Adresse einer inzwischen gelöschten Ressource auf, greift zuerst die Weiterleitung auf die aktuelle Adresse. Erst der Folgeaufruf liefert found: false mit dem hinterlegten Weiterleitungsziel. In diesem Fall entstehen also zwei Weiterleitungen nacheinander.

found: true bedeutet, dass die Adresse auflösbar ist, nicht dass die Ressource auslieferbar ist. Ein deaktiviertes Produkt ohne hinterlegtes Weiterleitungsziel liefert found: true. Diesen Fall muss die Storefront selbst erkennen, indem sie das Ergebnis des anschließenden Ladeaufrufs prüft.

Aufbau des Feldes `redirect`

redirect ist immer ein Pfad und beginnt mit /, es ist keine absolute URL. Der Wert kann direkt als Location-Header gesetzt werden. Zwei Formen sind möglich:

eine SEO-URL des Ziels, beispielsweise /herren/schuhe
eine technische Shop-URL, wenn zum Ziel keine SEO-URL existiert, beispielsweise /?wsvc=Category&id=135-98530

Beide Formen werden vom Shop aufgelöst und können unverändert verwendet werden.

Voraussetzung für Weiterleitungen gelöschter Ressourcen

Ein Weiterleitungsziel für eine gelöschte Ressource wird nur ausgegeben, wenn im Shop redirectToParentCategory aktiv ist. Standard ist aktiv, siehe urls.redirects. Ist die Option deaktiviert, verhält sich eine gelöschte Ressource wie eine Ressource ohne hinterlegtes Ziel.

Fehlercodes

Code	HTTP	Beschreibung
`invalidParameters`	400	`url` fehlt, ist kein String, oder es wurden weitere Query-Parameter mitgegeben. Der Body enthält die Liste der beanstandeten Parameter.

GET urls/product

Folgender Aufruf liefert die Adresse eines Produkts. Verwenden Sie ihn, um in Listen, Suchergebnissen oder Empfehlungen Links auf Produktseiten zu erzeugen, ohne das URL-Schema des Shops in der Storefront nachbauen zu müssen. Beispiel-Aufruf

GET https://<ihr-shop>.de/api/v1/urls/product?productId=146-78608

Parameterübersicht

Parameter	Typ	Beschreibung
`productId`	string	Pflichtfeld ID des Produkts. Weitere Query-Parameter werden mit `invalidParameters` abgelehnt.

Beispiel-Response

{
  "url": "/herren/schuhe/sneaker-air-146-78608"
}

Zurückgegeben wird die aktuelle SEO-URL des Produkts als Pfad. Existiert für das Produkt keine SEO-URL, ist es die technische Shop-URL.

Statuscodes

Kann das Produkt nicht geladen werden, antwortet der Endpunkt mit 404 Not Found und leerem Body. Fehlt productId oder wurden weitere Query-Parameter mitgegeben, antwortet der Endpunkt mit 400 Bad Request und dem Fehlercode invalidParameters.

GET urls/category

Folgender Aufruf liefert die Adresse einer Kategorie, beispielsweise für den Aufbau der Navigation oder von Breadcrumbs. Beispiel-Aufruf

GET https://<ihr-shop>.de/api/v1/urls/category?categoryId=135-98530

Parameterübersicht

Parameter	Typ	Beschreibung
`categoryId`	string	Pflichtfeld ID der Kategorie. Weitere Query-Parameter werden mit `invalidParameters` abgelehnt.

Beispiel-Response

{
  "url": "/herren/schuhe"
}

Zurückgegeben wird die aktuelle SEO-URL der Kategorie als Pfad. Existiert keine SEO-URL, ist es die technische Shop-URL.

Statuscodes

Kann die Kategorie nicht geladen werden, antwortet der Endpunkt mit 404 Not Found und leerem Body. Fehlt categoryId oder wurden weitere Query-Parameter mitgegeben, antwortet der Endpunkt mit 400 Bad Request und dem Fehlercode invalidParameters.

Weiterführende Links

Storefront API Basics - Basis-URL, Subshop-Auswahl über die Domain, Session-Handling und Fehlerformat.
Storefront API Katalog - Produkt- und Kategoriedaten zur ermittelten ID laden.
urls - URL (Webadressen) - Aufbau der SEO-URLs und Verhalten bei nicht mehr gültigen Adressen.
Storefront API Session-Handling - Übergabe der Session an eine Template-Seite.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Unterstützte Methoden

Methoden für die URL-Resolution

GET urls/identify

Parameterübersicht

Antwortfelder

Seitentypen

Antworten im Überblick

Beispiel-Response: vorhandene Ressource

Beispiel-Response: Startseite

Beispiel-Response: Template-Seite

Beispiel-Response: Alt-Adresse derselben Ressource

Beispiel-Response: gelöschte Ressource mit Weiterleitungsziel

Beispiel-Response: unbekannte Adresse

Auswertung in der Storefront

Aufbau des Feldes `redirect`

Voraussetzung für Weiterleitungen gelöschter Ressourcen

Fehlercodes

GET urls/product

Parameterübersicht

Beispiel-Response

Statuscodes

GET urls/category

Parameterübersicht

Beispiel-Response

Statuscodes

Weiterführende Links

​Unterstützte Methoden

​Methoden für die URL-Resolution

​GET urls/identify

​Parameterübersicht

​Antwortfelder

​Seitentypen

​Antworten im Überblick

​Beispiel-Response: vorhandene Ressource

​Beispiel-Response: Startseite

​Beispiel-Response: Template-Seite

​Beispiel-Response: Alt-Adresse derselben Ressource

​Beispiel-Response: gelöschte Ressource mit Weiterleitungsziel

​Beispiel-Response: unbekannte Adresse

​Auswertung in der Storefront

​Aufbau des Feldes redirect

​Voraussetzung für Weiterleitungen gelöschter Ressourcen

​Fehlercodes

​GET urls/product

​Parameterübersicht

​Beispiel-Response

​Statuscodes

​GET urls/category

​Parameterübersicht

​Beispiel-Response

​Statuscodes

​Weiterführende Links

Unterstützte Methoden

Methoden für die URL-Resolution

GET urls/identify

Parameterübersicht

Antwortfelder

Seitentypen

Antworten im Überblick

Beispiel-Response: vorhandene Ressource

Beispiel-Response: Startseite

Beispiel-Response: Template-Seite

Beispiel-Response: Alt-Adresse derselben Ressource

Beispiel-Response: gelöschte Ressource mit Weiterleitungsziel

Beispiel-Response: unbekannte Adresse

Auswertung in der Storefront

Aufbau des Feldes `redirect`

Voraussetzung für Weiterleitungen gelöschter Ressourcen

Fehlercodes

GET urls/product

Parameterübersicht

Beispiel-Response

Statuscodes

GET urls/category

Parameterübersicht

Beispiel-Response

Statuscodes

Weiterführende Links