Proxying GraphQL Requests to API Route Handlers in Catalyst/Next.js

Next.js API Route Handlers let you create backend endpoints which you can use to proxy client requests to the backend so that you can protect your private environment variables. Instead of exposing sensitive credentials on the client side, the client calls your route, which makes the request with the credentials stored on the backend.

In this blog, we’re going to show you how we built an API Route Handler in Catalyst to proxy requests from client-side Makeswift components. You’ll see how you can fetch dynamic backend data from BigCommerce when building your own components in Makeswift. 

We’ll start by building a backend endpoint that returns product data from BigCommerce through the GraphQL Storefront API. We’ll then work on incorporating the data into a Makeswift component to be rendered. 

And don’t forget – Makeswift components can take user input. You’ll see how user input can determine which product data is fetched in Makeswift and how it then gets proxied to BigCommerce.

Here’s a sneak peak of the proxy in action:

If you want a video version of this tutorial, watch it here: https://www.youtube.com/watch?v=Qi_DkSQviU0

Prerequisites

Follow the Getting Started with Catalyst documentation to create your Catalyst storefront using One-Click Catalyst. To follow along, choose the option to use sample catalog data. Then, follow the Local Development documentation to pull down the code and run locally.

Create an API Route handler 

We’re going to create an API route handler that requests product data from BigCommerce. In the App Router, each route corresponds to a folder in the /app directory. Start by creating the following file directory which corresponds to a /api/product route. Next.js reserves the route.ts filename for route handlers.

Route handlers export a function that returns the API response data. The name of the function corresponds with the HTTP method name. In our case, we’re making a GET request. Add the following inside the route.ts file so that the route returns sample product data when called. Let’s quickly check that the route works as expected. Run the development server and visit the /api/product path in the browser (on the port where your server is listening). You should see Next.js return JSON data from the endpoint.

Fetch product-specific data

To make the route return product-specific data, we can use a dynamic route segment to represent a parameter for the product ID. The dynamic segment captures the slug as a parameter, which we can use to access content for a particular sample. 

Update your file structure to include the dynamic segment:

To check the dynamic route, let’s access the slug parameter and return it in our API response. Update the route.ts file so that the handler accepts the `params` prop. API route handlers accept the request object as the first parameter, so we’ve added it also. Try visiting the /api/product/123 and /api/product/124 path in the browser. At the moment, you should see the same product data returned, but with an entityID based on the path you entered.

Next, we want the data to actually come from BigCommerce. We’re going to fetch the data from the GraphQL Storefront API using the Catalyst Client. Let’s update the route.ts file to include the fetch call. In our case, we want to query the product name and image. The entityID from the slug parameter gets passed to the call to fetch product-specific data.

Now that this route returns product data from your store’s catalog, you’ll need the actual product IDs when you call the path in the browser. In this tutorial, the sample products have an entityID of 123 and 124, so when I visit the /api/product/123 and /api/product/124 paths in the browser, those corresponding products are returned from the store.

Create the Makeswift Component 

We’re going to create a product card component in Makeswift that fetches product data through the API route handler. To start, update your file directory to include a my-product-card/client.tsx file inside the lib/makeswift/components folder that comes with your OCC Catalyst app.

We’ll start by hard-coding the product data into the component. Create the product card component by copying the following into your my-product-card/client.tsx file: Now we need to register the component so that it becomes available to use inside of Makeswift. Create a registration file, register.ts for your product card. Register the component by copying the following inside of the registration file. The component will show up as “My Product Card” inside a “Catalog” folder in the Component Tray. We’ll leave the props property empty for now. Check out the Makeswift documentation to learn more about component registration. You need to import registered components so that they show up in the Component Tray.

To do this, copy the following line into the `core/lib/makeswift/components.ts` file which comes with your OCC Catalyst app when you install it.

You should now see this new component inside of the Component Tray in Makeswift.

Proxy the request to the API Route Handler

Now it’s time to actually make a call to BigCommerce using the API Route Handler. Update your Makeswift component code to include a fetch call to the route we created. In the following code, don’t forget to use the actual product IDs for your catalog when you make the fetch call.

To fetch different products from BigCommerce, change the entity ID in the route. You should see the product card change in Makeswift to reflect the newly-fetched data. 

Next, we want you to be able to choose which product to render in Makeswift. 

First, adjust the client.tsx file so that the component receives the `entityId` prop. This prop should receive the entity ID for the product you choose in Makeswift.

Next, we’ll pass the entityId prop to the component from the register.ts file.

We’re going to use the ComboBox control to define the prop so that the products display as a list of options. The searchProducts utility function is already defined for you and fetches options to choose from when typing in the combobox.

Now, you should see a drop-down list of products to choose from in the properties of your component.

Fetch localized product data

The product component can fetch localized product data from BigCommerce. To follow along, you can translate the product data to French (fr locale) in your BigCommerce store. Update your API Route Handler file so that it accepts a `locale` search parameter, validates the locale that it receives, and passes it to BigCommerce when fetching product data.  

Update the product card client.tsx file so that the Makeswift component calls your route with the locale fetched from `next-intl`.  Last, you need to add the fr locale in Makeswift. When you switch to this locale, you should see the translated product data.

Learn more about translating dynamic data from BigCommerce. 

What’s next?  

Note that the Makeswift Product Card component that’s available out of the box in your OCC Catalyst app has several more features.

• It uses the VIBES Product Card component for responsive design and includes a fallback skeleton for loading or empty content. 

• It renders other product data like the price.  Quick tip! If you want your product card to include more data like the brand and prices, you’ll need to update the GraphQL query in your API Router Handler to fetch the data. You can test the GraphQL query in the GraphQL Playground before using it in the code.  If you want to return data that requires customer authentication, like pricing based on customer groups, you’ll want to pass the customer access token as a parameter when you make a call with the Catalyst Client. 

• It receives other user input from Makeswift.

Check out the Makeswift docs for more info on the controls that the finished Product Card component uses.