Storefront API URL-Resolution

Die URL-Resolution API dient dazu, eine Storefront-URL (insbesondere SEO-URLs) auf den passenden Shop-Inhalt aufzulösen. Damit kann das Frontend sein Routing auf sprechenden URLs aufbauen und erhält als Ergebnis, ob die URL beispielsweise zu einem Produkt oder einer Kategorie gehört – inklusive der erforderlichen internen IDs. Anschließend lassen sich die Detaildaten gezielt über die Katalog API abrufen. Ein typischer Ablauf ist: Die Storefront übermittelt eine URL wie /herren/schuhe/sneaker, die API liefert den Zieltyp (z. B. Kategorie) und die zugehörige Kategorie-ID zurück, und danach werden die Inhalte über die Katalog API geladen.

Unterstützte Methoden

Angabe aller Unterstützten Methoden.

Befehl	Endpunkte	GET	PUT	POST	DELETE
SEO-URLs erkennen	`urls/identify`
SEO-URL eines Produkts abrufen	`urls/product`
SEO-URL einer Kategorie abrufen	`urls/category`

SEO-URLs

GET urls/identify

Mithilfe des folgenden Aufrufs lässt sich ermitteln, wohin eine SEO-URL im Shop führt (Produkt, Kategorie, Inhaltsseite oder Startseite).

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

Im Response steht der Typ der URL und - je nach Typ - eine Ressource (z.B. eine ID oder ein Pfad).
Die API unterscheidet dabei zwischen folgenden Typen

Typ	Ressource	Beschreibung
`“Product"`	Produkt-ID	Verweist auf eine Produktseite und enthält die zugehörige Produkt-ID, zu dem die URL gehört.
`“Category"`	Kategorie-ID	Verweist auf eine Kategorieseite und enthält die Kategorie-ID, die über die URL aufgerufen wird.
`“View"`	Template-Pfad	Verweist auf eine Shop-Seite oder ein Template, die über den angegebenen Pfad geladen wird.
`“Startpage"`	—	Verweist auf die Startseite des Shops. Für diesen Typ wird keine zusätzliche Ressource ausgegeben.

Beispiele

Erfolgreiche Identifikation (Haupt-URL) Die URL zeigt direkt auf ein Produkt. In der Antwort werden der Typ und die zugehörige ID angegeben.

GET https://<ihr-shop>.de/api/v1/urls/identify?url=/products/awesome-widget

Beispiel-Response

{
  "type": "Product",
  "id": "12345"
}

Erfolgreiche Identifikation mit Weiterleitung

Veraltete URLs werden erkannt und auf die aktuelle URL weitergeleitet. Zusätzlich zur ID wird ein Redirect mitgeliefert.

GET https://<ihr-shop>.de/api/v1/urls/identify?url=/products/old-product-name

Beispiel-Response

{
  "type": "Product",
  "id": "12345",
  "redirect": "/products/awesome-widget"
}

Kategorie

Wenn die URL zu einer Kategorie führt, enthält die Antwort eine Kategorie-ID.

GET https://<ihr-shop>.de/api/v1/urls/identify?url=/categories/electronics

Beispiel-Response

{
  "type": "Category",
  "id": "789"
}

Startseite

Wenn die URL zur Startseite führt, gibt es keine zusätzliche (ID-)Ressource im Response.

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

Beispiel-Response

{
  "type": "Startpage"
}

Ungültige URL

Wenn die URL dem System nicht bekannt ist, antwortet die API mit einem „404 Not Found”.

GET https://<ihr-shop>.de/api/v1/urls/identify?url=/non-existent-page

Beispiel-Response

HTTP/1.1 404 Not Found

GET urls/product

Mithilfe des folgenden Aufrufs lässt sich die SEO-URL eines Produkts anhand der Produkt-ID ermitteln.

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

Parameterübersicht

Parameter	Typ	Beschreibung
`productId`	string	Pflichtfeld ID des Produkts, dessen SEO-URL ermittelt werden soll.

Beispiel-Response

{
  "url": "/url/to/product"
}

Wenn das Produkt nicht gefunden wurde, gibt die Anfrage 404 Not Found zurück.
Bei Erfolg gibt die Anfrage 200 OK zurück inklusive der im Beispiel genannten Ausgabe der SEO-URL des Produkts im Body.

GET urls/category

Mithilfe des folgenden Aufrufs lässt sich die SEO-URL einer Kategorie anhand der Kategorie-ID ermitteln.

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

Parameterübersicht

Parameter	Typ	Beschreibung
`categoryId`	string	Pflichtfeld ID der Kategorie, deren SEO-URL ermittelt werden soll.

Beispiel-Response

{
  "url": "/url/to/category"
}

Wenn die Kategorie nicht gefunden wurde, gibt die Anfrage 404 Not Found zurück.
Bei Erfolg gibt die Anfrage 200 OK zurück inklusive der im Beispiel genannten Ausgabe der SEO-URL der Kategorie im Body.

Schnittstellen

Admin Interface API

Storefront API

Weitere

Unterstützte Methoden

SEO-URLs

GET urls/identify

Beispiele

Erfolgreiche Identifikation mit Weiterleitung

Kategorie

Startseite

Ungültige URL

GET urls/product

Parameterübersicht

Beispiel-Response

GET urls/category

Parameterübersicht

Beispiel-Response

​Unterstützte Methoden

​SEO-URLs

​GET urls/identify

​Beispiele

​Erfolgreiche Identifikation mit Weiterleitung

​Kategorie

​Startseite

​Ungültige URL

​GET urls/product

​Parameterübersicht

​Beispiel-Response

​GET urls/category

​Parameterübersicht

​Beispiel-Response

Unterstützte Methoden

SEO-URLs

GET urls/identify

Beispiele

Erfolgreiche Identifikation mit Weiterleitung

Kategorie

Startseite

Ungültige URL

GET urls/product

Parameterübersicht

Beispiel-Response

GET urls/category

Parameterübersicht

Beispiel-Response