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.