> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Storefront API URL Resolution

> Resolve speaking storefront URLs to products or categories via the Storefront API URL resolution and obtain the IDs needed for Catalog API requests.

The URL Resolution API is used to resolve a storefront URL (especially SEO URLs) to the matching shop content. This lets the frontend build its routing on speaking URLs and obtain the result of whether the URL belongs to, for example, a product or a category — including the required internal IDs.

The detail data can then be specifically retrieved via the Catalog API. A typical flow is: the storefront submits a URL such as `/herren/schuhe/sneaker`, the API returns the target type (e.g. category) and the corresponding category ID, and afterwards the contents are loaded via the [Catalog API](/en/schnittstellen/storefront-api/storefront-api-katalog).

***

## Supported methods

List of all supported methods.

| **Command**                    | **Endpoints**   | **GET**               | **PUT**             | **POST**            | **DELETE**          |
| ------------------------------ | --------------- | --------------------- | ------------------- | ------------------- | ------------------- |
| Identify SEO URLs              | `urls/identify` | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |
| Retrieve SEO URL of a product  | `urls/product`  | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |
| Retrieve SEO URL of a category | `urls/category` | <Icon icon="check" /> | <Icon icon="ban" /> | <Icon icon="ban" /> | <Icon icon="ban" /> |

## SEO URLs

### GET urls/identify

The following call can be used to determine where an SEO URL leads in the shop (product, category, content page, or start page).

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/urls/identify?url=<url>
```

The response contains the type of URL and — depending on the type — a resource (e.g. an ID or a path).\
**The API distinguishes between the following types**

| **Type**      | **Resource**  | **Description**                                                                              |
| ------------- | ------------- | -------------------------------------------------------------------------------------------- |
| `"Product"`   | Product ID    | Refers to a product page and contains the corresponding product ID to which the URL belongs. |
| `"Category"`  | Category ID   | Refers to a category page and contains the category ID called up via the URL.                |
| `"View"`      | Template path | Refers to a shop page or template that is loaded via the specified path.                     |
| `"Startpage"` | --            | Refers to the start page of the shop. No additional resource is output for this type.        |

#### Examples

Successful identification (main URL)

The URL points directly to a product. The type and the corresponding ID are specified in the response.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/urls/identify?url=/products/awesome-widget
```

**Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "type": "Product",
  "id": "12345"
}
```

#### Successful identification with redirect

Obsolete URLs are recognized and redirected to the current URL. In addition to the ID, a redirect is also delivered.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/urls/identify?url=/products/old-product-name
```

**Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "type": "Product",
  "id": "12345",
  "redirect": "/products/awesome-widget"
}
```

#### Category

If the URL leads to a category, the response contains a category ID.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/urls/identify?url=/categories/electronics
```

**Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "type": "Category",
  "id": "789"
}
```

#### Start page

If the URL leads to the start page, there is no additional (ID) resource in the response.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/urls/identify?url=/
```

**Example response**

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "type": "Startpage"
}
```

#### Invalid URL

If the URL is not known to the system, the API responds with a "`404 Not Found`".

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/urls/identify?url=/non-existent-page
```

**Example response**

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
HTTP/1.1 404 Not Found
```

### GET urls/product

The following call can be used to determine the SEO URL of a product based on the product ID.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/urls/product?productId=<productId>
```

#### Parameter overview

| **Parameter** | **Type** | **Description**                                                               |
| ------------- | -------- | ----------------------------------------------------------------------------- |
| `productId`   | string   | **Required field**<br />ID of the product whose SEO URL should be determined. |

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "url": "/url/to/product"
}
```

* If the product was not found, the request returns `404 Not Found`.
* On success, the request returns `200 OK` including the output of the product's SEO URL mentioned in the example in the body.

### GET urls/category

The following call can be used to determine the SEO URL of a category based on the category ID.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<your-shop>.de/api/v1/urls/category?categoryId=<categoryId>
```

#### Parameter overview

| **Parameter** | **Type** | **Description**                                                                |
| ------------- | -------- | ------------------------------------------------------------------------------ |
| `categoryId`  | string   | **Required field**<br />ID of the category whose SEO URL should be determined. |

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "url": "/url/to/category"
}
```

* If the category was not found, the request returns `404 Not Found`.
* On success, the request returns `200 OK` including the output of the category's SEO URL mentioned in the example in the body.