Routing Strategies

In the previous lab exercise, you made use of the site.route query to directly fetch records matching the current URL path for category and product detail pages.

In this section, we’ll take a closer look at how your storefront’s URL structure might affect the way you make use of site.route. Let’s consider two possible approaches to routing and data fetching for a product detail page.

Approach 1

The URL pattern you used in the previous lab exercise made the product page context explicit in the URL: mystore.com/product/{path}. Since you already know that you need to query on a products, you can also query all the product details you need in the same query. For example:

query MyRouteQuery($myPath: String!) {
  site {
    route(path: $myPath) {
      node {
        __typename
        ... on Product {
          entityId
          name
          sku
          defaultImage {
            isDefault
            altText
            urlOriginal
          }
          prices {
            basePrice {
              currencyCode
              value
            }
          }
        }
      }
    }
  }
}

Approach 2

A common alternative is a terser approach to URL paths, which avoids an explicit segment like “product”. With this approach, any product (or category or brand) page would simply be represented by the pattern mystore.com/{path}. With this routing structure, you do not know ahead of time what type of entity patches the path. There are two steps for routing with this approach. First, you need to find out what type of page the path is leading to by writing a query for all possible page types. For example:

query MyRouteQuery($myPath: String!) {
  site {
    route(path: $myPath) {
      node {
        __typename
        ... on Banner {
          id
          name
        }
        ... on Blog {
          id
          name
        }
        ... on Brand {
          id
          name
        }
        ... on Cart {
          id
        }
        ... on Category {
          id
          name
        }
        ... on ContactPage {
          entityId
          name
        }
        ... on Product {
          entityId
          name
        }
        ... on RawHtmlPage {
          entityId
          name
        }
        ... on Variant {
          entityId
        }
      }
    }
  }
}

The query results will tell you exactly what type of page exists at the given path. Below is an example of the results:

{
  "data": {
    "site": {
      "route": {
        "node": {
          "__typename": "Product",
          "id": "UHJvZHVjdDoxMjY=",
          "name": "Awesome Shirt"
        }
      }
    }
  }
}

The results tell you that the given path is leading to a product page. Now you can go back to use this information to route to the appropriate destination.

Redirects

Additionally, you can query for page redirect information. The redirects field can tell you if a page has been assigned a redirect URL, where the page will redirect to, and will give you the redirect URL if one is available.

For example, to get redirect information about the path in the previous query you can add the redirect field.

query MyQuery($myPath: String!) {
  site {
    route(path: $myPath) {
      node {
        __typename
        ... on Product {
          entityId
          name
          sku
        }
        ... on Category {
          entityId
          name
        }
      }
      redirect {
        fromPath
        to {
          ... on ProductRedirect {
            entityId
            path
          }
          ... on CategoryRedirect {
            entityId
            path
          }
        }
        toUrl
      }
    }
  }
}

The fragments under the to field (shown here as ...on ProductRedirect) will return results if the redirect types match. The query above is asking for information if the redirect is a product or category redirect. You can include as many fragments here as you want for manual, product, brand, blog post, or page redirects.

The response of the example query will look something like the response below:

{
  "data": {
    "site": {
      "route": {
        "redirect": {
          "fromPath": "/product-path/",
          "id": "UmVkaXJlY3Q6Mg==",
          "to": {
            "id": "UHJvZHVjdDoxMjY=",
            "path": "/new-product-path/"
          },
          "toUrl": "https://petonline.us/cool-shirt/"
        }
      }
    }
  }
}

This example response tells you that the path /product-path/ redirects to /new-product-path/ and provides a URL. For headless storefronts the URL provided in the response will be a URL that BigCommerce thinks it should be. Whether this URL is accurate on your own headless storefront depends on the routing scheme that you are using.

Redirect Behavior

The redirectBehavior is a GraphQL argument that determines if the query will follow the redirect or ignore the redirect when fetching node results. The node results are providing data on what type of page exists on the given path.

If you tell the query to ignore the redirect, the results will give you information about where the path redirects. For example:

query MyQuery($myPath: String!) {
  site {
    route(path: $myPath, redirectBehavior: IGNORE) {
      node {
        __typename
        ... on Product {
          entityId
          name
          sku
        }
      }
      redirect {
        fromPath
        to {
          ... on ProductRedirect {
            entityId
            path
          }
        }
        toUrl
      }
    }
  }
}

In the example results above, you can see that /striped-t-shirt/ redirects to /cool-striped-t-shirt/. Notice that the node section is null because the given path is not the correct path anymore.

If you tell the query to follow the redirect, the results will give you information as if the given path is still the correct path. For example:

query MyQuery($myPath: String!) {
  site {
    route(path: $myPath, redirectBehavior: FOLLOW) {
      node {
        __typename
        ... on Product {
          entityId
          name
          sku
        }
      }
      redirect {
        fromPath
        to {
          ... on ProductRedirect {
            entityId
            path
          }
        }
        toUrl
      }
    }
  }
}

In the example results above, you can see again that /striped-t-shirt/ redirects to /cool-striped-t-shirt/. This time there is information in the node section because the query is fetching results from the existing path, not the old path that redirects to /cool-striped-t-shirt/.

These redirectBehavior options put the decision-making for redirects in the hands of your storefront application. In the case where a redirect exists in the route data, BigCommerce gives you the context about that redirect but ultimately allows the storefront to determine how it wants to deal with that information.

Resources

• GraphQL Storefront API Reference