DEVDOCS-5007: [new] GQL Storefront, Extended GQL LookupURL Route Redirects

docs/api-docs/storefront/graphql/graphql-redirects.mdx

@@ -0,0 +1,368 @@
+**GraphQL Storefront API**
+# Guide to Working with Redirects
+
+BigCommerce's GraphQL Storefront API lets frontend developers modify [Redirects](/docs/rest-content/store-content/redirects##upsert-redirects) from a store. These built-in capabilities also allow developers to customize their hosted or headless storefronts with Redirects.
+
+<Callout type="information">
+  #### Create a Redirect API
+  The [Create a Redirect](/docs/rest-content/store-content/redirects#create-a-redirect) API endpoint is deprecated. Use the [Upsert Redirects](/docs/rest-management/redirects) API endpoint instead to update new redirect data.
+</Callout>
+
+The GraphQL Storefront API lets you set the following redirect attributes and more:
+- Redirect site traffic to a manual URL on the domain
+- Set redirections for GQL types such as: Product, Page, Brand, Blog Post, and Category
+- Use redirect behavior to enable an optional `FOLLOW` or `IGNORE` argument in the `route`s `path`
+
+## Prerequisites
+
+To complete the guide you will need the following:
+- A BigCommerce Store with Multi-Storefront enabled
+- A [Storefront API](/docs/rest-authentication/tokens#create-a-token) token
+- A 301 redirect set 
+- An understanding of [Routes](/docs/storefront/headless/site-content#routes)
+
+For more information on formatting the request payload, see the query example section of the [GraphQL Storefront API Overview](/docs/storefront/graphql#querying-within-a-bigcommerce-storefront).
+
+## Redirect to a product
+
+Divert traffic from an old URL to a new URL accross all storefronts. Set the `path` with the product's URL to redirect traffic from an old product URL, to a new product URL. In this example, the old URL is set to redirect product to a new product URL in the query. The response confirms that traffic is diverting from the old product URL, to the new product URL.
+
+<Callout type="information">
+  #### Optional Redirect Node Arguments
+  If you add optional arguments on the `route` node, check that the correct `redirectBehavior` is in use. For instance, when using the default `IGNORE` to set a manual URL redirect >>>still testing behavior>>>
+</Callout>
+
+<tabs items={['Request', 'Response']}>
+  <tab>
+  ``` graphql filename="Example query request: Redirect to a Product" showLineNumbers copy 
+  query {
+    site {
+      route(path: "/chambray-towel-1/", redirectBehavior: FOLLOW) {
+        node {
+          ... on Product {
+            name
+            entityId
+          }
+        }
+        redirect {
+          to {
+            __typename
+          }
+          toUrl
+          fromPath
+        }
+      }
+    }
+  }
+  ```
+  </tab>
+  <tab>
+  ``` graphql filename="Example query response: Redirect to a Product" showLineNumbers copy
+  {
+  "data": {
+    "site": {
+      "route": {
+        "node": {
+          "name": "Test Product",
+          "entityId": 127
+        },
+        "redirect": {
+          "to": {
+            "__typename": "ProductRedirect"
+          },
+          "toUrl": "https://www.test-store.com/test-product/",
+          "fromPath": "/chambray-towel-1/"
+        }
+      }
+    }
+  }
+  }
+  ```
+  </tab>
+</tabs>
+
+
+<a href="https://developer.bigcommerce.com/graphql?playground_tab=ProductRedirect" target="_blank">**Try it in GraphQL Playground**</a>
+
+## Redirect to a page
+
+Run this query across your storefront data to redirect to a new page.
+
+<tabs items={['Request', 'Response']}>
+  <tab>
+  ``` graphql filename="Example query request: Redirect to a Page" showLineNumbers copy 
+  query {
+    site {
+      route(path: "/home-and-kitchen/", redirectBehavior: FOLLOW) {
+        node {
+          ... on Page{
+            name
+            entityId
+          }
+        }
+        redirect {
+          to {
+            __typename
+          }
+          toUrl
+          fromPath
+        }
+      }
+    }
+  }
+  ```
+  </tab>
+  <tab>
+  ``` graphql filename="Example query response: Redirect to a Page" showLineNumbers copy
+  {
+  "data": {
+  "site": {
+    "route": {
+      "node": {
+        "name": "Towel Collection",
+        "entityId": 6
+      },
+      "redirect": {
+        "to": {
+          "__typename": "PageRedirect"
+        },
+        "toUrl": "https://www.test-store.com/chambray-towel/",
+        "fromPath": "/home-and-kitchen/"
+      }
+    }
+  }
+  }
+  }
+  ```
+  </tab>
+</tabs>
+
+
+<a href="https://developer.bigcommerce.com/graphql?playground_tab=PageRedirect" target="_blank">**Try it in GraphQL Playground**</a>
+
+
+## Site redirect to a blog post
+
+
+<tabs items={['Request', 'Response']}>
+  <tab>
+  ``` graphql filename="Example query request: Redirect to a Blog Post" showLineNumbers copy 
+  query {
+    site {
+      route(path: "/your-first-blog-post/", redirectBehavior: FOLLOW) {
+        node {
+          ... on BlogPost{
+            name
+            entityId
+          }
+        }
+        redirect {
+          to {
+            __typename
+          }
+          toUrl
+          fromPath
+        }
+      }
+    }
+  }
+  ```
+  </tab>
+  <tab>
+  ``` graphql filename="Example query response: Redirect to a Blog Post" showLineNumbers copy
+  {
+  "data": {
+    "site": {
+      "route": {
+        "node": {
+          "name": "2023 Events Calendar",
+          "entityId": 3
+        },
+        "redirect": {
+          "to": {
+            "__typename": "BlogPostRedirect"
+          },
+          "toUrl": "https://www.test-store.com/blog/2024-events-calendar/",
+          "fromPath": "/your-first-blog-post/"
+        }
+      }
+    }
+  }
+  }
+  ```
+  </tab>
+</tabs>
+
+  <a href="https://developer.bigcommerce.com/graphql?playground_tab=BlogPostRedirect" target="_blank">**Try it in GraphQL Playground**</a>
+
+
+## Redirect to a category
+
+In this example, a site redirect query is redirecting traffic from an old category URL, to a new category URL.
+
+<tabs items={['Request', 'Response']}>
+  <tab>
+  ``` graphql filename="Example query request: Redirect to a Category" showLineNumbers copy 
+  {
+    site {
+      route(path: "/home-office/", redirectBehavior: FOLLOW) {
+        node {
+          ... on Category {
+            name
+            entityId
+          }
+        }
+        redirect {
+          to {
+            __typename
+          }
+          toUrl
+          fromPath
+        }
+      }
+    }
+  }
+  ```
+  </tab>
+  <tab>
+    ``` graphql filename="Example query response: Redirect to a Category" showLineNumbers copy
+    {
+    "data": {
+      "site": {
+        "route": {
+          "node": {
+            "name": "Home Office",
+            "entityId": 29
+          },
+          "redirect": {
+            "to": {
+              "__typename": "CategoryRedirect"
+            },
+            "toUrl": "https://www.test-store.com/housewares/",
+            "fromPath": "/home-office/"
+          }
+        }
+      }
+    }
+  }
+  ```
+  </tab>
+</tabs>
+
+
+<a href="https://developer.bigcommerce.com/graphql?playground_tab=CategoryRedirect" target="_blank">**Try it in GraphQL Playground**</a>
+
+## Redirect to a brand
+
+Create a site redirect to divert traffic from an old URL to a new URL. In this example, a site redirect query is redirecting traffic from an old brand URL, to a new brand URL.
+
+<tabs items={['Request', 'Response']}>
+  <tab>
+  ``` graphql filename="Example query request: Redirect to a Brand" showLineNumbers copy 
+  {
+    site {
+      route(path: "/hand-made-joy/", redirectBehavior: FOLLOW) {
+        node {
+          ... on Brand {
+            name
+            entityId
+          }
+        }
+        redirect {
+          to {
+            __typename
+          }
+          toUrl
+          fromPath
+        }
+      }
+    }
+  }
+  ```
+  </tab>
+  <tab>
+    ``` graphql filename="Example query response: Redirect to a Brand" showLineNumbers copy
+    {
+      "data": {
+        "site": {
+          "route": {
+            "node": {
+              "name": "Hand Made Joy",
+              "entityId": 38
+            },
+            "redirect": "https://www.test-store.com/brands/hand-made-joy/"
+          }
+        }
+      }
+    }
+  ```
+  </tab>
+</tabs>
+
+
+<a href="https://developer.bigcommerce.com/graphql?playground_tab=BrandRedirect" target="_blank">**Try it in GraphQL Playground**</a>
+
+## Manual URL redirect
+
+Run this query and divert traffic from an old page URL, to a new page URL.
+
+<tabs items={['Request', 'Response']}>
+  <tab>
+  ``` graphql filename="Example query request: Redirect to a manual input URL" showLineNumbers copy 
+  {
+    site {
+      route(path: "/contact-us/", redirectBehavior: FOLLOW) {
+        redirect {
+          to {
+            __typename
+          }
+        toUrl
+        fromPath
+      }
+    }
+  }
+}
+  ```
+  </tab>
+  <tab>
+    ``` graphql filename="Example query response: Redirect to a manual input URL" showLineNumbers copy
+{
+  "data": {
+    "site": {
+      "route": {
+        "redirect": {
+          "to": {
+            "__typename": "PageRedirect"
+          },
+          "toUrl": "https://www.test-store.com/contact-us/",
+          "fromPath": "/lets-chat/"
+        }
+      }
+    }
+  }
+}
+  ```
+  </tab>
+</tabs>
+
+
+<a href="https://developer.bigcommerce.com/graphql?playground_tab=ManualRedirect" target="_blank">**Try it in GraphQL Playground**</a>
+
+### FAQs
+
+**Query is returning `null` values**
+
+The `redirect` node query returns a `null` value when details for a given path are missing. Check that the 301 redirect contains all the required details. Add any missing details and run the query again. For more information about 301 redirects see [301 Redirects](https://support.bigcommerce.com/s/article/MSF-301-Redirects?language=en_US).
+
+## Resources
+### GraphQL documentation
+[GraphQL Storefront API Overview](/docs/storefront/graphql#querying-within-a-bigcommerce-storefront)
+[Routes](/docs/storefront/headless/site-content#routes)
+
+### REST API reference
+[Storefront API](/docs/rest-authentication/tokens#create-a-token)
+[Upsert Redirects](/docs/rest-management/redirects)
+[Redirects](/docs/rest-content/store-content/redirects#create-a-redirect)
+
+### Support articles
+[301 Redirects](https://support.bigcommerce.com/s/article/MSF-301-Redirects?language=en_US)